(Brady 











Advanced 


Programmer's Guide 
to OS/2 


Thuyen Nguyen 
and 
Robert Moskal 





Brady Books ® New York 


Copyright © 1989 

by Simon & Schuster, Inc. 

All rights reserved, including the 
right of reproduction in whole or 
in part in any form. 





Simon & Schuster, Inc. 
Gulf + Western Building 
One Gulf + Western Plaza 
New York, NY 10023 


DISTRIBUTED BY PRENTICE HALL TRADE 
Manufactured in the United States of America 
123 4 5 6 7 8 9 10 

Library of Congress Cataloging in Publication Data 


Nguyen, Thuyen. 
Advanced programmer’s guide to OS/2 / Thuyen Nguyen, Robert Moskal. 
p. cm. 
Includes index 
1. OS/2 (Computer operating system) I. Moskal, Robert. 1962- 
II. Title. 
QA76.76.063N48 1988 
005.4’ 469- -dcl19 88-30237 
CIP 


ISBN 0-13-642935-1 


Dedication 


To the Sensuous Particular 


Acknowledgements 


Many thanks to Jo Ann Schop for her valuable reading of the manuscript. To our 
editor Milissa Koloski, publisher Michael Mellin, production coordinator Mia 
McCroskey, and Brady members Laura McKenna and Marjorie Gursky: thanks for 
making this first book an easier project. Lastly, thanks are due to the staff at 
PageWorks for the care they took in preparing this book for print. 


Limits of Liability and Disclaimer of Warranty 

The authors and publisher of this book have used their best efforts in preparing this book and the programs 
in it. These efforts include the development, research, and testing of the theories and programs to deter- 
mine their effectiveness. The author and publisher make no warranty of any kind, expressed or implied, with 
regard to these programs or the documentation contained in this book. The author and publisher shall not 
be liable in any event for incidental or consequential damages in connection with or arising out of the 
furnishing, performance, or use of these programs. 


Trademarks 

Microsoft, MS OS/2 and MS-DOS are registered trademarks of Microsoft Corporation. 

IBM and PC-DOS are registered trademarks of International Business Machines Corporation. 

The term OS/2 as used herein shall in every case be construed to mean the Microsoft product OS/2 except 
as noted otherwise in the text. 


Table of Contents 


Introduction 


Chapter 1—0S/2 Overview 


OS/2 and 80286 Protected Mode 

Multitasking Concepts 

The Role of the Operating System in a Multitasking Enviroment 
The Relationship between OS/2 and DOS 


Chapter 2—Using Processes and Threads 
Processes 

Threads 

Priority Levels 

Process Functions 

Creating a Process 

Thread Functions 

Using Threads and Processes Efficiently 


Chapter 3—Inter-Process and Inter-Thread Communications 
Using Flags for Signaling 

Using Critical Sections for Mutual Exclusion 

Semaphores 

Using Semaphores for Mutual Exclusion 

Using Semaphores for Synchronization 

Using Semaphores for Signalling 

Data Transfer Between Processes 


Chapter 4—Memory Management Concepts and Functions 


System Memory 

Virtual Memory 

Config.Sys Parameters for Memory Management 
Memory Functions 


Chapter 5—Queue 

Features of Queue 

Create, Open, and Close Queues 
Sending and Receiving Data with Queue 


1X 


103 
110 
lz 
126 
148 
149 


165 


166 
166 
Vr 
172 


225 
225 
ar at 
232 


V1 


Advanced Programmer's Guide to OS/2 


Chapter 6—Handling of External Events 
Signal Handling 


Chapter 7—Date and Timer Services 


Date Functions 
Timer Functions 
DosTimerAsync 


Chapter 8—Error Handling and Message Retrieval 


DosErrorClass 

Exception Handling 
Hard Error Handling 
Message Retrieval Facility 


Chapter 9—Linking and Dynamic Linking 
Introduction to Linking 

Introduction to Dynamic Linking under OS/2 
Module Definition Files 

Linking Together Applications 

The LINK Utility 

Example of a Dynamic Link Library 
Load-time Dynamic Linking Examples 
Implementing Run-time Dynamic Linking 
The Procedure for Run-time Dynamic Linking 
DosGetModHandle 

DosLoadModule 

DosFreeModule 

DosGetModName 

DosGetProcAddr 

DosGetResource 

Example of Run-time Dynamic Linking 


Chapter 10—File and Device |/O Functions 


File and Device Naming Conventions 

File Opening Mode and File Attributes 

File I/O, File Pointer, and File Protection 
Standard I/O: STDIN, STDOUT, and STDERR 


Chapter 11—Disk, Directory, and File Management 
Disk Management Functions 

Directory Management Functions 

File Management Functions 


255 
256 


273 


273 
277 
280 


287 


288 
293 
297 
298 


315 


a15 
S17 
320 
334 
342 
359 
362 
364 
365 
366 
367 
369 
370 
a11 
a12 
374 


379 


381 
382 
ool 
414 


417 
419 
437 
444 


Table of Contents 


Chapter 12—OS/2 Execution Enviroment 


Foreground and Background Sessions 
Within Each Session 

Session Manager Components 

API for Creating and Managing Sessions 


Chapter 13—Video Functions 


Background and Foreground Screen Groups 

OS/2 Video Subsystem 

Presentation Manager Application and OS/2 Application 

Text-Based Applications, Dialog Manager, and Presentation Manager 
Video System Configuration and Display Set-up 

Cursor Control Functions 

Text Display Functions 

Screen Scrolling 

ANSI Support Functions 


Chapter 14—Keyboard Functions 


Scan Codes and Shift States 

Logical Keyboard Buffer and Keyboard Handle 
Keyboard Access 

Keyboard Inputs 

Keyboard Status 


Chapter 15—Mouse API Functions 


Pointer Draw Screen Driver 

Mouse Drivers Parameters for CONFIG.SYS 
Mouse Operations 

Mouse Operation Functions 

Mouse Support Under the Presentation Manager 
Family API Mouse Support 

Supported Mouse Devices 


Chapter 16—Advanced Video Functions 


Logical and Physical Video Buffers 
Background Pop-Ups 

Manipulating the Logical Video Buffer 
Manipulating the Physical Video Buffer 
Screen Saving and Restoring Techniques 
Font Control 

A Few Tips for Using Video Functions 


489 


49] 
49] 
494 
495 


509 


510 
510 
512 
514 
514 
5S2Z 
538 
555 
569 


573 


574 
575 
577 
579 
590 


599 


59D 
601 
602 
605 
640 
640 
641 


643 


644 
646 
654 
660 
668 
677 
680 


Vil 


Vlil 


Advanced Programmer's Guide to OS/2 


Chapter 17—Advanced Device I/O Functions 


Installing Your Own Device Subsystem 
Keyboard Manipulation Functions 


Chapter 18—Device I/O Control Functions 
DosDevIOCTL 

Keyboard IOCTL Functions 

Logical Disk IOTCL Functions 

Parallel Port IOCTL Functions 

Asynchronous Port IOCTL Functions 


Chapter 19—Input/Output Privelege Level Segment 


Features of IOPL Segment 

Setting Up an IOPL Segment 

Guidelines for Developing IOPL Segments 
IOPL Segment and the 80386 

IOPL Functions 


Chapter 20—Character Device Monitors 


Device Monitor Architecture 

Developing Device Monitors 

Device Monitor Registration’s Time Window 
Device Monitors and DOS TSRs 


Chapter 21—DOS and OS/2 


Conversion of High-Level Language Programs 
Conversion to API Calls 

Converting 8088 Assembly to 80286 Assembly 
Compatibility Box and FAPI 

Other Conversion Issues 


Appendix A 
Appendix B 
Appendix C 
Appendix D 


index 


681 


681 
702 


705 


706 
709 
715 
435 
743 


773 
774 
776 
ree 
778 
779 


785 


786 
789 
803 
821 


823 


824 
824 
825 
827 
831 


833 
853 
858 
865 


871 


Introduction 


oo 
The Twilight of DOS 





a (r) evolution in the personal computing industry that started in the early 

1980s. When the original PC-DOS was introduced in 1981 as the software 
platform for the original IBM PC, personal computers as such did not yet exist. 
Personal computing was barely beyond the esoteric province of electronics 
hobbyists and hackers. PC-DOS and the PC architecture quickly became the 
standards that grew with the industry, widely accepted by a majority of new 
personal computer users. Ironically, this standard on which so much has subse- 
quently depended, was itself the ad-hoc product of an urgent need to produce an 
operating system as quickly as possible. PC-DOS’s original developers had not an 
inkling of the uses to which the personal computer, and their system software, 
would eventually be put. 

Ata time when most personal computers had a maximum of 64K of RAM, the 
640K addressing limit of the 8086/8088 CPU and the DOS operating system must 
have seemed practically boundless. The first shipment of PCs came with 16K of 
RAM and one 180K single-sided floppy disk drive. Within a year 256K and two 360K 
drives were the standard configuration. This remarkable leap is emblematic of the 
explosion that spawned an entire industry almost overnight. 

Subsequent years have been marked by constant innovation in IBM PC hard- 
ware and software. The 8086/8088 CPU gave way to the faster, more powerful 
80286 and 80386 microprocessors. The original 180K floppy drive was replaced by 
the 360K drive which was further supplemented with hard disks, and the 1.2MB 
high-density and 3.5 inch floppy disk drives. 

DOS was upgraded again and again to support each of these innovations. 
Unfortunately, DOS is inherently tied to the features and limitations of the 8086/ 
8088 microprocessor. While it can run on the new CPUs in PC-type systems, it treats 
them as if they are 8086/8088 microprocessors, ignoring many of the features that 
make them fast and powerful. Thus, even though the hardware supports it, these 
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machines are incapable of multitasking and addressing extended memory under 
DOS. While this shortcoming alone did not necessarily doom DOS to obsoles- 
cence, developments in application software fueled by the insatiable demands of 
sophisticated “power users” most certainly did. 

If the original designers of DOS can be faulted at all, it is for lacking the gift of 
prophecy. Working ata time when centralized corporate computing was the norm, 
they were simply not in a position to predict that eventually individual computer 
users would demand a tremendous amount of computing power on their desktops. 
DOS was designed for the hackers and hobbyists of the late 1970s. It grants the 
programmer absolute power over the machine with little concern for safeguards 
or programming structure. DOS-based applications have full access to every part 
of the computer; every memory location can be accessed, including those used by 
the operating system and other programs. Every device attached to the system can 
be directly manipulated by applications. 

Nonetheless, more and more sophisticated applications were developed to 
meet the growing market’s demands. First users found that the personal computer 
could be used to do real work in a variety of ways, then they discovered that doing 
real work required being able to do more than one thing at a time. Soon they 
wanted to move data from a database to a word processing program in order to 
prepare a report, or to use a calculator utility while entering data into a spread- 
sheet. 

This forced developers to invent applications which used DOS in ways for which 
it was ill designed. “Pop-up” programs, such as SideKick from Borland, were 
developed to provide users with utilities that could be invoked while using other 
applications. These were implemented as TSR (Terminate and Stay Resident) 
programs which reside in memory until they are called into the foreground with 
a “hot-key” sequence. Many users happily loaded up their systems with TSRs. 
Unfortunately, these memory-resident programs eat up RAM, leaving even less 
than 640K available for application programs. Problems arose with different T'SRs 
attempting to use the same space in memory. Because T'SRs are activated by 
hooking into DOS interrupts (and because of the way in which DOS handles those 
interrupts) having a number of TSR programs in memory often resulted in erratic 
system performance. 

Another solution to the demands of the sophisticated user, “integrated” 
software, combines spreadsheet, database, document preparation, and communt- 
cations software in a single package. These programs also take up a tremendous 
amount of memory, so much so that many must be implemented through the use 
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of overlays (code segments are hustled in from disk when they’re needed, overwrit- 
ing code segments already in RAM in the process). 

Several extensions to DOS allow for greater addressing capabilities and multi- 
tasking. However, all of these must be implemented through software since they 
are still fundamentally tied to the limitations of the 8088. The major shortcoming 
of extensions was that the application developer was placed in the uncomfortable 
position of having to produce several versions of each application, one for each 
DOS enhancement. 

For this reason, we believe that OS/2 will be a boon to all, but especially to 
developers who at last have a standard environment which provides system services 
that meet the needs of today’s advanced applications. OS/2, however, is not merely 
a standard for today which will be supplanted as conditions in the personal 
computing industry change tomorrow. The central concept governing the design 
of OS/2 is inherent extendability. Unlike DOS, extensions to the OS/2 kernel are 
indistinguishable from the kernel itself by applications. This means that the 
functionalities of the basic system can be enhanced without making older applica- 
tions obsolete. This is precisely how the Presentation Manager and the LAN 
Manager will be implemented. For these reasons, because OS/2 answers the needs 
of today’s applications and is open to the as yet unforeseen demands of the future, 
we feel that it will be the operating system of choice for a long time to come. 


Our Audience 


This book is intended for the programmer or developer who has already 
successfully developed personal computer applications, or who is at least familiar 
with the issues involved in doing so. With this book he or she will learn to take 
advantage of OS/2’s advanced features in order to begin creating the next 
generation of personal computer applications today. We address primarily devel- 
opers who wish to develop end-user-oriented applications to co-exist happily in 
OS/2’s multitasking environment, not those who wish to create OS/2 extensions 
(such as their own graphical programming interface) for use by other applications. 

While OS/2 is similar in many ways to operating systems for larger computers, 
it is not so far removed from DOS. Programmers with a DOS background, as well 
as those making the transition from larger computers to PCs, will do well with the 
material in this book. Windows programmers will find the transition to OS/2 
especially pleasant, as OS/2 ameliorates many of the frustrations characteristic of 
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Windows programming. DOS programmers who are used to the freedom allowed 
by DOS will have the most difficult transition to the more structured OS/2 
environment. We do our best throughout the book to make this transition as 
smooth as possible. In addition we feel that this book will be of interest to advanced 
end users and others responsible for the evaluation and implementation of new 
technologies. It will provide such readers with a clear idea of what OS/2 can and 
cannot do. 

This book is specifically for programmers who work in high-level languages (C, 
Pascal, FORTRAN, COBOL, FORTH, etc.). Unlike the DOS application program 
interface, which is meant to be called from assembly language routines, the 
OS/2 API (Application Program Interface) works seamlessly with high-level 
languages. Because OS/2 is especially congenial to the C language, our program- 
ming examples and listings for function calls are in C. However, the lessons learned 
in the book can be translated from C to any other popular high-level language, or 
to 80286 assembly language. 

We do not assume that our readers have had any formal computer science 
training. Because OS/2 is a sophisticated operating system, we occasionally 
introduce theoretical operating system concepts 1n order to fully explain a point. 
When we do so we take pains to explain our terms as clearly as possible. 


How To Use This Book 


This book is very much for the programmer. We have organized it to provide a 
thorough introduction to OS/2 for the new arrival, as well as to serve as a reference 
that experienced OS/2 programmers will not want to be without. Consequently, 
this book is primarily a reference text that brings together a large quantity of 
information in one place. However, the structure of this reference text is different 
from most. It is not a full-blown narrative. It is not necessary to read it from front 
to back or even to read all of each chapter in order to learn the desired 
information. 

Material is grouped by topic and presented in the manner in which it will 
actually be used. For example, there are separate chapters on manipulating the 
mouse and the keyboard. The programmer who is unfamiliar with either device 
will find a presentation of the major issues involved in manipulating it. Following 
this are sections devoted to each major issue containing instructions on how to 
accomplish various operations using combinations of API functions. Finally, 
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within each section there is a detailed explanation of each API function, including 
restrictions for real-mode applications and programming examples. Program- 
ming examples range from simple illustrations of how to call functions that return 
complex data structures, to complex examples of some of the issues involved in the 
topic. We have dispensed with the usual program play-by-play within the text, 
because the examples are heavily annotated and usually directly reflect the 
concepts introduced earlier in the discussion. The programmer who is new to a 
topic will be prepared for the example by the reading, and will find the example 
a useful guide. The advanced programmer will find the examples a useful 
touchstone without having to wade through a lot of extraneous prose. 

The Advanced Programmer’s Guide to OS/2Z has two sections. Chapters 1-12 cover 
topics that will remain unchanged under OS/2 no matter what the future brings. 
This material covers the system kernel, including such topics as multitasking, 
memory management, and various system services (such as timers and the file 
system services) which will always have to be used by OS/2 applications. The first 
part of the book also covers information needed in order to link together 
applications. Because the first part of the book covers the timeless aspects of 
OS/2 programming, it demands more careful reading than the second. Particu- 
larly important are the chapters on tasks (Chapter 2) and interprocess communi- 
cations (Chapter 3) which provide the information necessary to write applications 
that take full advantage of OS/2’s multitasking capabilities. 

The second part of the book (beginning with Chapter 13) covers the inherently 
extendable aspects of OS/2. This part of the book covers the API functions for 
accessing various devices supported by OS/2. Because OS/2 device services can be 
replaced with other services, their exact functionality may change in the future. 
However, the structure of these interfaces will remain the same. For example, the 
Presentation Manager, IBM’s graphical programming and user interface, exten- 
sively augments OS/2’s standard API functions. The second part of the book 
covers device manipulation under Version 1.0 and provides programmers with the 
concepts and structure that will always apply, even in future versions of OS/2. 


Notes on Conventions 


Throughout the text we use the unsigned data type. This corresponds to the 
unsigned int type supported by C. The current version of the Microsoft C compiler 
defaults unsigned to unsigned int. We have used the abbreviated notation to 
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conserve space. If your compiler does not support this default feature, use the full 
data type definition: wnsigned int. 

Throughout the text, functions and their parameters are presented initially in 
a brief form for readers who simply need a reminder, and then in greater detail. 
In all cases, detailed descriptions of parameters appear inside grey boxes which do, 
in some cases, cover more than one page. Function names appear in bold the first 
time they are used in a discussion specifically about them (but not when they are 
referenced with regard to some other function). Parameter names are always 
italicized. Code examples appear in a different font from the text to ensure proper 
spacing and clarity. 

When individual lines of code are longer than the book’s pages will allow, the 
overrun is placed on the next line, on the extreme right, like this: 


printf (“/nAllocation of shared seg failed, error: 
%d”, ret); 


When typing this line of code, the reader should not place a return after error:, 
but rather continue typing as if the printed code appeared on a single line. 


Chapter 1 





OS/2 Overview 


development for 80286-based microcomputers. 80286, even 80386, micro- 

processors have been available for some time, but OS/2 is the first operating 
system to fully capitalize on the architectural features available in the protected or 
native mode of the 80286. With an appropriate operating system these features 
allow for the simultaneous execution of multiple programs, and create the ability 
to address up to | gigabyte of memory. 

The expanded memory system introduced in 1986 broke DOS’s 640K barrier and 
allowed application programs to address more memory. However, the limitation 
on the size of a DOS executable module remains at 640K (minus the size of the 
DOS kernel and any memory resident programs). Expanded memory is imple- 
mented through bank switching, which uses software to transfer blocks of memory 
between high DOS memory (from 640K to 1 MB) and additional non-DOS- 
addressable RAM storage. 

Some individual applications can take advantage of expanded memory and 
some DOS enhancements provide access to expanded memory as well as a certain 
amount of multitasking. By and large these attempts at providing an expanding 
operating environment have been hampered by the need to remain compatible 
with PC-DOS. Because of this, all attempts to overcome the limitations inherent 
to DOS have relied on software solutions to manage expanded memory and to 
execute several programs at once. Most of these enhanced environments perform 
so slowly on 8088 machines that they are unusable. Only the increased speed of 
the 80286 and 80386 machines makes such environments perform satisfactorily. 
Unfortunately, they still cannot take advantage of any of the new microprocessors’ 
special features designed especially for the implementation of a multitasking, 
large memory operating system. These solutions have been the equivalent of 
running a V-8 engine on only four cylinders. OS/2, on the other hand takes full 
advantage of the new generation of microprocessors and represents a true leap in 
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the design of operating systems for IBM and compatible microcomputers. 

OS/2 gives application programs resources that have heretofore only been 
available in operating systems designed for larger computers. Besides providing 
a true multitasking environment, OS/2 also allows every program within the 
system to address a virtual memory space of | gigabyte. This address space is then 
mapped onto a physical address space of up to 16 megabytes. A system which allows 
for programs to address a memory space that is larger than the computer’s actual 
physical memory (RAM) is called a virtual memory system. Although primitive virtual 
memory systems are available in the current PC-DOS environment, OS/2 is less 
dependent on software because it uses special hardware features in the 80286 
implement virtual memory. 

Under OS/2 many applications are concurrently active within the same envi- 
ronment. A great part of the operating system’s job is to provide a secure 
multitasking system. OS/2 must enable programs to communicate with one 
another (to share data and synchronize execution); it must also handle requests 
for system resources (e.g., memory, and devices, such as the monitor, keyboard, 
disk drive, etc.). Applications communicate with OS/2 through the Application 
Program Interface (API) Functions. ‘The greater part of this book will be spent on 
discussing and demonstrating the use of API functions for communicating among 
applications and for manipulating various devices. 

Maintaining a secure multitasking operating system radically changes the 
relationship between applications and the operating system. An application can 
no longer maintain an opportunistic relationship with the operating system. For 
example, under DOS, an application commonly uses DOS calls to obtain system 
services, when convenient, but it can also bypass DOS entirely to go to BIOS 
interrupt routines, or to directly manipulate a device, when these methods prove 
more efficient. In the OS/2 environment the API calls are the primary interface 
between application programs and computer resources. For reasons inherent to 
the protected mode concept, API functions are the programmer’s only recourse 
for communication between different applications. This does not mean that the 
programmer must sacrifice performance, because OS/2 API calls are much more 
powerful and efficient than the corresponding PC-DOS functions. In cases where 
a programmer needs even greater functionality to access a device, OS/2 allows the 
programmer to specify his or her routines in place of OS/2 routines, or even to 
directly manipulate a device. 
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OS/2 and 80286 Protected Mode 


The special architectural features of the 80286 microprocessor determine 
OS/2’s structure and performance. When operating in protected mode, the 80286 
calls into play several registers not used at all in real mode (the mode in which DOS 
operates) and also takes advantage of special fields in the machine’s segment 
registers that are invisible in real mode. (The segment registers are used to address 
memory locations for the purposes of code execution, and data and stack 
manipulation.) These special features provide direct support to an efficient and 
secure multitasking operating system. Such a system requires: 


= Protection of operating system code and data from interference by 
applications, which lessens the chance of system failure; 


=" Protection of the resources of each application from interference by 
another, also lessening the chance of system failure; 


=" Expansion of the address space available to applications to | gigabyte; 


= The implementation of a virtual memory system, completely invisible to 
application programs; 


="Fast and efficient task-switching. 


Indirect Memory Addressing 


At the heart of the protected mode concept lies indirect memory addressing. ‘This 
mechanism is directly involved in the implementation of all the features listed 
above. Under indirect memory addressing, programs no longer have access to the 
addresses of the memory locations which they manipulate (whether for control 
transfer, or data access). In real mode, programs use a selector:offset combination 
for direct memory addressing. The selector refers to an address in memory, and 
the offset refers to a displacement in bytes from that location. Under OS/2, while 
programs still specify locations in memory segments using a selector:offset combi- 
nation, the selector no longer represents an address in physical memory, but is 
itself an offset on a special table maintained in memory, which contains the actual 
physical address of the desired physical memory segment. This table is called a 
descriptor table. 

Indirect memory addressing breaks the addressing limit in effect under DOS. 
Each selector can now refer to an entire 64K memory segment. Thirteen bits of 
the selector are used to specify a slot on the descriptor table. This results in a 
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maximum length for a descriptor table of 8191 slots, or 8191 64K memory 
segments addressable by a program (one half a gigabyte!). Because two such 
descriptor tables are maintained by the 80286, the address space available to any 
program is twice that, or 1 gigabyte. 

In real mode a selector is the address of an actual physical memory location, 
while the offset is a displacement of n (where offset=n) bytes from that address. 
Using a combination of a selector and different offset, a program addresses 
locations within a memory segment. In protected mode, however, a selector is not 
a physical memory address, but it is itself an offset, or pointer, to a special table 
maintained in memory by the 80286. Each slot on this table, called a descriptor 
table, contains the physical address of a memory segment (stored in a data 
structure called a descriptor), which is matched up with the program-specified 
selector automatically by the 80286. The offset in protected mode continues to act 
as a displacement which specifies an exact location in bytes, within a memory 
segment. (For a full discussion of the operation of the selector and offset in 
protected mode, see Chapter 19). 

In short, accessing memory segments in protected mode is a two-step process. 
A selector and an offset is specified by a program, and this selector is translated into 
a physical address by the 80286, which reads the corresponding descriptor for the 
selector from the descriptor table. OS/2 encodes additional information about 
each memory segment, such as its type (code segment, data segment, stack 
segment), its protection level, and whether or not the segment is actually present in 
physical memory. The combination of a two-step procedure for segment access, 
and the imbedding of information about the segment in the same data structure 
that contains its address, allows the 80286 to implement the protection mecha- 
nisms necessary to protect itself and other programs on the hardware level. These 
features will be outlined in the following three sections. 


Processes and Threads 


As was we mentioned earlier, there are always two descriptor tables present 
within the OS/2 environment. Two special registers are set aside for loading 
descriptor tables into memory, the Global Descriptor Table Register (GDTR), and the 
Local Descriptor Table Register (LDTR). The Global Descriptor Table (GDT) contains the 
addresses for memory segments that belong to the operating system, or that are to 
be accessible to every program running within the multitasking system. The 
second table, the Local Descriptor Table (LDT), contains the addresses for memory 
segments that belong to a single application. Another way of saying this is that the 
GDT represents the public address space for the entire system, while the LDT 
represents the private address space available to each application. 
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OS/2 implements multitasking by switching the Local Descriptor Table as often 
as it switches tasks. This means that there is always one unique GDT present within 
the system and a series of LDT's which varies in time, depending on which task is 
being executed. The instructions that change the contents of either the GDT 
Register or the LDT Register, and hence change descriptor tables, can only be 
issued by OS/2. Because each application is constrained to accessing memory 
segments with an offset to a descriptor table, each application can only address 
memory segments belonging only to its own private address space or to the public 
address space available to all applications. ‘This system makes it physically 
impossible for one application to gain access to memory segments belonging to 
another, thus preventing the accidental or malicious destruction of code and data. 
This is one of the protection mechanisms that give protected mode its name, and, 
as you can see, this protection is provided at the hardware level, making it both 
efficient and fail-safe. 

The collection of code and data segments bound by a common descriptor table 
is called a process. As we have seen the code and data of one process are protected 
from those of another through a hardware protection mechanism. All the code 
segments within a process have access to the same resources. They can address the 
same code and data segments and have access to any system resources requested 
on the behalf of the process. In fact when OS/2 launches a process it constructs 
an LDT for it. This makes the process a good representation of the idea of an 
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application. Generally speaking, each application within the multitasking system 
is implemented asa process (though it is possible to split an application into several 
processes). OS/2 implements multitasking by switching among processes very 
quickly, giving the illusion that multiple applications are executing simultane- 
ously. 

Within each process it is also possible to define entities known as threads. A 
thread is like a subroutine within a program which executes concurrently, or 
asynchronously, with other subroutines. In this way the functions of a program can 
be divided among a number of concurrently executing threads, all of which 
cooperate to accomplish the intended purpose of the program. 

Communication and coordination among threads is simple because global 
variables can be declared across every thread in a process. Because they are 
physically isolated from one another, communication and coordination among 
them is more difficult. OS/2 provides services that accomplish this. 


Protection (Privilege) Levels 


OS/2 protects the data and code of one application from being tampered with 
by another by maintaining a separate address space for each application and by 
restricting an application’s access to physical memory segments (by only allowing 
it to access memory indirectly, through an offset on a table—the selector). But this 
scheme does nothing to protect the operating system—remember, it is part of 
every task—from being over-written by an application. Such protection is achieved 
by taking advantage of special hardware within the 80286 which assigns a protec- 
tion level to every memory segment within the system. 

The 80286 provides four levels of protection, called privilege levels. These are 
arranged hierarchically, from 0 (maximum protection) to 3 (minimum protec- 
tion). Under OS/2, operating system code is privilege level 0 and applications run 
at the minimum protection level, 3. Level 2 (called the I/O Privilege Level) is used 
by special programs which need to directly manipulate I/O devices, and level 1 is 
not used at all. 

Programs at each privilege level can only manipulate data or code that are on 
the same or a less protected level. Therefore, the operating system (at level 0) can 
access memory segments belonging to all other tasks within the system. Applica- 
tion programs, however, do not have access to system (privileged) memory 
segments except in a controlled and indirect fashion. This is accomplished 
through a task-gate. A task-gate is a special hardware control transfer mechanism 
which allows code at a lower privilege level to branch to code in more privileged 
memory segments at certain restricted entry points like the beginnings of routines. 
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Information about the privilege level of each segment is kept both in its 
descriptor and in its selector. This information is maintained in both places 
because selectors are often passed to the operating system in order to identify a 
calling segment, and itis necessary that the operating system prevent such a calling 
procedure from gaining access to segments for which it has an insufficient 
privilege level. Naturally, any attempt bya task to reference a code or data segment 
with a higher privilege level meets with an error called a protection exception. 


Virtual Memory 


From now on every program within the system can address | gigabyte of memory 
which OS/2 maps onto a physical address space of up to 16 megabytes. An 
operating system that allows programs to address a memory space greater than the 
actual physical memory of a computer— memory overcommitment—is called a Virtual 
Memory System. In the past, virtual memory capabilities were only necessary for time- 
sharing systems running on larger computers such as Digital’s VAX/VMS or IBM’s 
VM where main memory has to be shared among a large number of users. The 
advent of OS/2 brings this powerful feature to the microcomputer environment. 

The OS/2 virtual memory system works by swapping memory segments be- 
tween main memory and a secondary storage unit such as a hard drive whenever 
there is not enough room in the main memory for all the segments that have been 
placed there during the execution of a program. Ifa routine calls a segment that 
is not currently in main memory, the segment will be loaded into main memory if 
there is room for it—as under DOS. If there isno room, some other segments that 
have not recently been used will be swapped to secondary storage in order to make 
room for it. This memory swappingis one of the regular tasks of an operating system. 
Memory swapping is often implemented under DOS, but on a primitive level: the 
application itself has to keep track of memory segments, an extra burden which 
naturally has a negative effect on performance. The OS/2 operating system 
includes a special module, called the Swapper, whose job is to to provide all tasks 
within the system with the illusion that all the memory segments they have 
allocated reside in main memory at the same time. Memory swapping is completely 
invisible to application programs, which simply address the virtual memory they 
think they have. 

OS/2 carries out segment swapping by cooperating directly with the 80286 
microprocessor. A special bitin each segment’s descriptor keeps track of whether 
the specified segment currently resides in physical memory or on the secondary 
storage device. Whenever the 80286 encounters an addressing attempt to a 
segment that does not reside in physical memory it generates an exception. This is 
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a re-startable error that activates the Swapper portion of the operating system to 
bring the desired segment into physical memory. Once the Swapper has done its 
job, the addressing attempt is restarted as if nothing had happened. 


Exceptions 


In the previous section we introduced the term exception, which we character- 
ized as arestartable error. Ina complex environment the idea ofa restartable error 
takes on great importance. Under DOS it is okay in most cases if a faulty 
application, or a conflict between an application and some memory resident 
program, occasionally causes the processor to “hang.” We can simply reboot and 
check to see that none of the data we have been working on has been corrupted. 
Under OS/2, where several applications may be running at once, we can no longer 
afford to let a fault in a single task drag down the whole system. It’s obvious that 
it would be inefficient to have to restart all the threads within the system every time 
one bombs out, but there is another more important reason why it is no longer 
allowable to let the processor enter into an undefined state (the definition of 
hanging). With multitasking, the complexity of the entire system can quickly reach 
the point at which it impossible for the user or programmer to determine the state 
of the overall system at any given moment. If the entire system is forced to 
terminate abnormally it will be quite likely impossible to determine what data has 
been corrupted. OS/2 solves this problem by having the CPU issue an exception 
every time a program attempts to perform an illegal operation. 

The 80286 issues many exceptions, each of them corresponding to a particular 
error, or class of errors. Whenever an exception is issued by the microprocessor, 
control is transferred to a special routine (called an exception handler), which 
either clears up the cause of the exception, and restarts the offending program, or 
simply terminates the program without crashing the entire system. OS/2 provides 
default exception handling routines for all the exceptions that can be generated 
by the 80286. Some of these are used to provide operating system functions, such 
as invoking the Swapper, but for most exceptions the default action taken by OS/ 
2 is to display an error message and to terminate the execution of the guilty 
program. For example, if a program attempts to address a memory location 
outside its local address space, by specifying a selector not within the bounds of its 
LDT, the processor issues a protection exception and terminates the program. 

OS/2 also allows the programmer to replace a default exception handler with 
one of his or her own specification. While this is not possible for every class of 
exception, it does give programmers the power to write applications that can, to 
a certain extent, anticipate and correct fatal errors on their part. This useful facility 
is discussed in Chapter 8. 
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Multitasking Concepts 


In the previous section we saw how OS/2 works with the protected mode 
architecture as a base for the implementation of efficient multitasking. In this 
section we will see how OS/2 puts the multitasking concept into motion by 
implementing task switching. 

Task switching is the way in which multitasking is implemented in a single 
processor system. The operating system switches between the executing programs 
very quickly, distributing a certain number of processor cycles to each. This is not 
the same thing as true multiprocessing where each program would have its own 
central processing unit. Nonetheless, multitasking by sharing the resources of a 
single processor among several processes, each made up of multiple concurrent 
threads, does possess several great advantages over executing programs sequen- 
tially. 

The most important advantage of multitasking arises from the fact that the 
computer actually contains several other processors in addition to the CPU. Each 
device controller (the video board, the disk controller, the communications 
port(s)) has its own processor to handle I/O between the system and the device. 
There is a significant lag between the time when the program executing in the CPU 
makes an I/O request to a device, and the time it takes the device to accomplish 
the I/O operation. In a single tasking system, the CPU spends the time of this lag 
just waiting for the completion of the I/O operation. ‘This time is wasted because 
the CPU remains idle. In a multitasking system another program (or another 
thread belonging to the same program) can be executed while a program or 
thread is waiting for the completion of an I/O request to a device. In cases where 
a program can be divided up into several threads, one, say, to read data from the 
hard drive, another to prepare this data through some sort of calculation, a third 
to display this data on the video screen, and a fourth to send this data to the 
communications port, the increase in the performance of the one program can be 
substantial. 

The next advantage of multitasking lies in the way in which the end user’s 
relationship to the computer changes. All of us are familiar with the frustration of 
waiting for our word processor to check the spelling of a document, or for the 
computer to re-index a large database, or re-calculate a spreadsheet. During these 
times we cannot continue to work. In a multitasking system the user can continue 
to add text to his or her document, while the spelling of each word is checked 
automatically as itis entered. Likewise, during the time when spreadsheet values 
are being recalculated, or a database is being indexed, the user can work on a 
document, while the computer has been downloading information from a bulletin 


10 Advanced Programmer's Guide to OS/2 


board all the while. This change makes computer users more satisfied, since they 
will spend less time waiting on the computer, and more productive, since the 
computer user is typically the slowest link in a computer system. 


Task Switching 


We explained earlier that OS/2 switches the local address space in the system 
by changing the contents of the Local Descriptor Table Register. But this is not yet 
the whole story as to how OS/2 implements multitasking. The implementation of 
multitasking requires that the operating system switch rapidly between executing 
programs or threads. Switching the LDT is only a part of this process. Switching 
between programs or threads when implementing multitasking is called task or 
context switching. 

In order to understand task switching one has to be able to imagine what goes 
on within the CPU when a program or thread is executing. Asa program executes, 
the contents of the registers in the machine are constantly changing in response 
to the instructions which the program issues. If one could take a “snapshot” of all 
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Figure 1.2 Task Switching. 
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the CPU registers one would have a perfect representation of the state ofa program 
at any given moment. This includes all the segment registers, the stack registers, 
and the LDTR. In order to switch among multiple programs OS/2 saves a “picture” 
of the CPU in memory every time it interrupts the execution of one program or 
thread to execute another one. Switching to the next task to be executed entails 
loading its “picture” from memory into the CPU and continuing to execute it from 
the point at which it was interrupted. 

The action of switching a task to the running state (loading it into the CPU) is 
called dispatching. OS/2 dispatches tasks on the basis of the thread. When OS/2 
switches between threads in the same process, the contents of the LDT register do 
not change. When OS/2 dispatches a thread in a process different from the one 
which was interrupted, the contents of the LDT register are changed. 


Thread Dispatching 


All the threads that are active within the system at any time form a pool from 
which the operating system dispatches threads one at a time, in a round-robin 
fashion. A dispatched thread temporarily has the CPU all to itself. Thread 
dispatching is performed by a module of the operating system called the Dispatcher/ 
Scheduler. ‘The Dispatcher institutes the task switch necessary to execute the next 
thread, while the Scheduler distributes processor cycles to all the active threads 
within the system. 

Notice that we have been speaking of active threads and dispatched threads. 
These are not the same thing. At any given time within the system there will be a 
number of active threads, but only one dispatched thread. In fact itis more proper 
to speak of the active threads within the system as the set of ready threads, and the 
dispatched thread as the running thread. A third state in which a thread can be 
found is the waiting state. A waiting thread is one which is waiting for an external 
event (such as the completion of an I/O operation). When the external event 
occurs (when the I/O operation has been completed) the operating system places 
the waiting thread back into the pool of ready threads. See figure 1.3 for the state 
diagram for a thread. 

There are two ways in which a running thread gives up control of the CPU. It 
can give up control of the CPU voluntarily, for example when it finishes executing, 
or while waiting for the return of a function call or the completion of a device 
I/O request. It would not be wise, however, to design an operating system under 
the presumption that all the active threads within the operating system will 
cooperate among themselves to share processor cycles equally. OS/2 will auto- 
matically preempt a running thread after a certain number of clock cycles has 
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Figure 1.3 Thread State Diagram. 


passed (this value is called the time slice), and go on to execute another. This makes 
OS/2 a preemptive scheduling system. In the same way OS/2 will not let a thread 
become “starved” for processor cycles, and will automatically dispatch a thread if 
it has waited too long. The length of the time slice (the amount of time the 
processor will devote to a thread) and the maximum amount of time that OS/2 will 
allow a thread to wait before being dispatched are both adjustable. 


Sessions 


Within the basic OS/2 operating system only one program at a time can have 
control of the video adapter, keyboard, and mouse. This means that only one 
program at a time can be accepting user input or displaying information on the 
video screen. In order to allow multiple programs to accept input and display 
output, under OS/2, each instance of a program runs as a separate session. 
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(Multiple copies of an application can run under OS/2.) The user switches 
between sessions using an OS/2 module called the Sesszon Manager. The session 
currently selected by the user has control of the video adapter, the keyboard, and 
the mouse, and is called the foreground session. Any other applications active in the 
system run as background sessions. Applications running as background sessions 
continue to receive processor cycles from the Dispatcher (they continue to run), 
but they cannot receive information from the keyboard or the mouse, nor can they 
display output directly on the video screen. 

The multiple session concept (with one forground session and many back- 
ground sessions) 1s inplemented with logical video, keyboard, and mouse buffers. 
Every session within the system is provided with a logical video, keyboard, and 
mouse buffer by OS/2. These logical buffers are like virtual devices in which I/O 
data from sessions is stored. The logical buffers of the current foreground session 
are bound to the actual physical buffer of each device. This means that any input 
from the physical keyboard or mouse is sent directly to the current foreground 
application. Any data sent by the foreground session to its logical video buffer is 
displayed on the video screen. A background session cannot receive information 
from its logical keyboard or mouse buffer, but it can continue to write to its logical 
video buffer. The data in its video buffer, however, will not be displayed on video 
screen until the session is switched into the foreground. It is possible, however, to 
allow a a program in a background session to pop-up messages to the foreground 
session, in the manner of a TSR program; and also to monitor for “hot-key” 
sequences in the same manner. At times in this book you will also see a session 
referred to as a screen group. 

When the Presentation Manager becomes available, several applications will 
execute within a single session or screen group. That is, several applications will 
be able to share the video screen at a time. 
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The Role of the Operating System ina 
Multitasking Environment 


The OS/2 operating system in conjunction with the protected mode features 
of the 80286 is directly responsible for the implementation of the multitasking 
virtual memory concept. The Swapper module of the operating system imple- 
ments the segment swapping needed to give each program the illusion that all its 
memory segments reside in physical memory at the same time. The Dispatcher 
module implements the task switching required for multitasking. The Session 
Manager allows the user to interact with many programs through a single key- 
board, mouse, and video screen. However all these features can be thought of as 
going on “behind the backs” of application programs. These features do not 
overtly determine the relationship between application programs, and _ develop- 
ers, and the OS/2 operating system. 

OS/2 must provide system services to applications within the protected mode 
environment. System services fulfill functions that allow applications to access 
resources and devices, such as physical memory, disk drives, video adapters, the 
keyboard, the mouse, etc. However in a multitasking system this situation is 
complicated because the operating system must allocate access to a small number 
of devices (a micro system normally has only one hard drive, monitor etc.) among 
a potentially large number of applications. Many devices can only be accessed one 
application at a time. For these sorts of devices OS/2 sets up a mutual exclusion 
mechanism, which allows only one application at a time to access a device. The 
foreground/background session concept discussed in the previous session is one 
such mechanism, which ensures that only one application at a time can have access 
to the keyboard, mouse, and video screen. For other resources and devices OS/ 
2 sets up a scheduling mechanism which lines up requests for services and resolves 
them one at a time in the order in which they came in. In a multitasking 
environment the operating system is tranformed from a mere provider of services 
to the indispensible mediator that allows the multitasking system to work . 

This state of affairs has two consequences for the way in which applications will 
be written under OS/2. First, applications have to go through the operating system 
to request the use of computer resources, to assure that they can run concurrently 
with other programs. (It is actually possible for programs to by-pass OS/2 calls for 
system services, but it is not recomended that they do so under normal circum- 
stances.) This may seem like a real hardship for DOS programmers fond of 
bypassing DOS calls to go to the faster BIOS calls, or direct device manipulation; 
this is necessary, however, to maintain the integrity of the system. In any case, even 
the most die-hard “shirt sleeves” programmers should find the performance of the 
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OS/2 functions satisfactory. The second consequence is a corollary of the first: 
programs written to run under OS/2 will have to be “well-intentioned programs”: 
they will have to be designed in such a way that they cooperate with other programs 
in the sharing of certain resources. OS/2 provides a special set of API functions 
that allow programs to communicate with one another in order to avoid conflicts 
among themselves. 


API Functions 


OS/2 provides a rich set of functions that allows programs to request systems 
services from the operating system, and that also allow programs to coordinate 
their execution with other programs, as well as exchange data. This set of functions 
is called the Application Program Interface (API) Functions. This set is divided into two 
general groups: those functions used to provide access to devices, and those 
functions that provide basic system services, interprocess execution control, and 
communication. 

The API function setis implemented through dynamic link libraries. A dynamic 
link library is an execution time library, whose code segments are not physically 
bundled together with the execution module of the calling program (as was the 
case under DOS). The code segments that contain the functions in a dynamic link 
library are brought into physical memory only when they are called for by a 
program. It is as if the operating system knows where these routines are located, 
but does not fetch them until they are needed. In addition, once a routine is 
brought into memory, a single copy can be shared among many applications. The 
“load on call” feature results in significantly smaller execution modules for 
programs that use dynamic link libraries, while the ability to share a single copy of 
a dynamic link library routine across many applications results in more efficient 
use of memory across the entire system. It is possible for application developers 
in the OS/2 environment to define their own dynamic link libraries, and hence to 
extend the standard API functions provided by OS/2. The introduction of this 
powerful feature into the microcomputing environment brings up complex issues 
which we will endeavor to sort through later in this book. 

API functions are called like any other external routines, through a Call and 
Return protocol. 

For assembly language programs, the parameters are pushed onto the stack in 
their order of occurrence. Control is tranfered to the API routine through a Call 
instruction. ‘The Call instruction pushes the return address of the calling routine 
onto the stack in the form selector:offset. When the API routine assumes control 
the stack contains all the parameters, as well as the return address of the calling 
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routine. However, the stack pointer points to the top of the stack (the end at which 
the stack grows). Because the 80286 stack grows down, this actually a lower location 
in memory called the bottom of the stack frame. In order to retrieve the parameters 
sent to it, the handling routine must move the the stack pointer upwards, past the 
return address (two words), and to the very first parameter in the parameters list 
(see figure 1.4). When it finishes the API routine, it restores the stack, pushes any 
returned parameters onto the stack, always places error codes in the AX register, 
and returns control to the calling program. 

These functions are called as external library routines for high level languages 
such as C. They take the form of a Far Call, Return combination. The above 
described method of pushing routine parameters onto the stack in the order which 
they occur is called the Pascal convention. The C convention is the reverse of this; 
the last argument is pushed on the stack first. However C programs, which use API 
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Figure 1.4 Stack Frame. 
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functions will not have to explicitly declare them as Pascal calls if the appropriate 
file “.H” appears in the program’s declaration section’. A program simply makes 
a normal far call: a number of parameters are passed to the function, and often 
a number of parameters are passed back to the calling program by the function. 
Parameters take the form of variables and pointers to memory locations. These 
pointers designate ASCII strings when the information that must be transfered to 
the operating system is variable length, and data structures when it is more 
complex. Complex data structures are generally returned by a class of API 
functions, called Query functions, which are used by applications to query the 
operating system about the status of a device or an operation. 

If a function call fails, OS/2 returns an error number to the calling program. 
OS/2 provides a service which helps a program to decide on its next course of 
action when a function call has failed. 


Devices Under OS/2 


In this section we summarize the manner in which devices are supported by 
OS/2, and the different methods which applications can use to access a device. 
This section serves as an introduction to the relationship that all OS/2 applications 
will have with devices. We wish to draw attention to the inherent flexibility of the 
OS/2 device interface, the way in which it is, by nature, extendable. 

A device is any hardware component connected to the system. The keyboard, 
mouse, video screen, video adapter, parallel ports, serial ports, printers, and disk 
drives are all examples of devices supported by OS/2. For each system device, 
OS/2 provides a device driver and a device subsystem. ‘The device subsystem uses 
the device driver to handle the I/O to the device. An OS/2 application uses the 
dynamic link API routines provided by the subsystem to obtain access to a device. 
Thus the device subsystem is the mediator between applications and the device 
driver. 

For example, the video subsystem uses the video driver to manipulate the video 
adapter. The video subsystem also provides video functions so applications can 
access the video adapter. The same method is used for accessing the keyboard, 
files, serial ports, parallel ports, and disk drives. 

As long as the functions provided by a device subsystem provide all the services 
needed by an application, the program does not need to use anything but these API 
functions. Under circumstances where the services provided by the subsystem are 
not adequate for the needs of a program, there are methods by which a program 
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can extend the functionality of a device subsystem, bypass the subsystem to directly 
manipulate the device driver, or even to bypass the device driver to directly 
manipulate the physical device. ‘These methods are listed below, and a discussion 
of them faciliates an understanding of the issues that will be of importance in the 
later chapters on advanced device manipulation. The methods for extending a 
subsystem include: 

= Replacing the functions provided by the device subsystem with the applica- 

tion own’s routines. This is also called extending the subsystem. 


=" Using device monitor functions. 
= Using device I/O control functions provided by OS/2. 
#" Using an I/O privilege level program to directly manipulate devices. 


The first method allows an application to replace a routine that is part of the 
device subsystem with one of its own. For example, if the application wants to 
control the print-screen function of the video subsystem, it can substitute its own 
VioPrtScrn function for the one provided by the video subsystem. Whenever a 
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Figure 1.5 Diagram of subsystem, and device driver. 
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print-screen is requested by the user, the substituted print-screen function can 
send the contents of the screen to a file instead of the parallel port. This method 
requires that the application use the register function provided by the device 
subsystem (i.e., VioRegister for video subsystem, MouRegister for mouse subsys- 
tem, and KbdRegister for keyboard subsystem.) Using these three register 
functions, an application can replace parts of a device subsystem with routines of 
its own specification (up to the point of replacing the entire subsystem with one 
of its own). This method cannot be used with the file and device I/O subsystems. 
If a device subsystem is extended in this manner, there is no difference between 
the new function and the one which it replaced as far as application programs are 
concerned. Both are implemented as dynamic link libraries, and are called by 
applications in the exact same manner as standard API functions. This what we 
meant by the integral extendability of OS/2 in the introduction. This feature 
ensures that OS/2 will be able to evolve to meet future developments in the field. | 

A device monitor allows the application to intercept or modify the data sent 
from a device driver to the device subsystem. A device monitor, however, can only 
be implemented for device drivers that provide monitor services, such as keyboard 
drivers, and printer drivers. Certain device drivers do not provide monitor 
services. These include the video driver, serial port, and disk drive device drivers; 
installation of a device monitor for such devices is impossible. 

Device I/O control functions (DevlOCtl) are provided by the device drivers for 
use by the device subsystem to manipulate the device driver. OS/2 applications, 
however, can use these functions to bypass the device subsystem altogether and 
manipulate the device driver. Most DevlOCtl functions provide similar services to 
those provided by the device subsystem. Their use is not recommended, because 
it may disable some of the protection mechanisms enforced by OS/2. There are 
a few DevIOCtl functions, however, which must be used in order to manipulate 
devices like serial ports, parallel ports, and disk drives. 

If an application requires direct access to a device via 80286 instructions such 
as IN or OUT (e.g., for the manipulations of the registers on the video adapter), 
it must be executed as an I/O privilege level program (IOPL). IOPL programs 
execute at privilege level 2 while other applications execute at privilege level 3. 
IOPL programs also monopolize the CPU while they are executing—no level three 
threads are dispatched at this time. IOPL programs, however, can only be used for 
non-interrupt driven devices. If the device requires an interrupt to notify the 
program of input or output, a device driver must be written to handle the device. 
We will explain the criteria involved in choosing to write IOPL programs instead 
of device drivers in Chapter 19. 
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interprocess Communications and Control 


The following diagram illustrates the normal state of OS/2’s multitasking 
environment. Several applications are running simultaneously. Some applica- 
tions are composed of multiple processes; most are composed of multiple threads. 
The operating system will resolve conflicts between all the active threads when it 
comes to distributing system resources. But in order to avoid chaos, with all this 
simultaneity going on, a certain amount of communication between the agents is 
needed at each level. This is to say that programs written for OS/2 must be well- 
intentioned. Threads within the same process will have to be able to communicate 
with one another, especially if the work done by one thread depends on the work 
being done by another. In the same way processes within the same application may 
need to communicate or exchange data to accomplish the purpose of the 
application. It may even be necessary or desirable for one application to exchange 
data or communicate with another (such as when several applications are working 
on the same data set, or ifa communications program needs to pass data to a text 
editor or database) 

There are a great many API functions whose purpose is to allow applications, 
processes, and threads to communicate with one another, and for each of these to 
adjust their execution in response to external events. In other words, these 
functions allow them to cooperate with one another in order to accomplish a job. 
These functions can be loosely grouped into two categories: those used to allow 


Application 2 Application 1 
Process 2 Process 1 Process 1 
Thread Thread Thread Thread Thread 

1 3 2 1 1 


Figure 1.6 Applications, Processes, Threads 
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processes and threads to send and receive data and signals, and those that are used 
for execution control. 

The idea of sending data and signals between processes and threads is easy 
enough to understand. Communication and data sharing between threads in the 
same process can in fact be accomplished without using API functions because 
threads within the same process share a common LDT. These threads can 
communicate with one another through global variables. Communication be- 
comes a real issue on the interprocess level. This is because the 80286’s protection 
scheme isolates processes from each other. OS/2 provides facilities which allow 
processes to exhange data and to send signals to one another. 

The execution control functions can also be divided into two types. There are 
those which allow a process or a thread to adjust its execution in response to an 
external event, such as a word processing application that saves the changes it has 
made in a file and terminates its execution in response to a signal from OS/2 
informing it that the user has terminated its session. Execution control functions 
allow threads or processes to terminate their own executions, to launch other 
simultaneous threads or process, to suspend their executions for a variable amount 
of time, or even in some cases to terminate the execution of other processes or 
threads. The other type of execution control provided by OS/2 is implemented 
through special system services which allow the programmer to quickly resolve 
certain situations that often occur in a multitasking environment. One such 
common situation is the problem of mutual exclusion*. The problem of mutual 
exclusion occurs when only one thread or process at a time can safely manipulate 
a set of data, but many threads or processes potentially have access to that data set. 
OS/2 provides special system services, accessible through API functions that allow 
the programmer make sure that only one thread or process at a time has access to 
such sensitive data. It is also often necessary to synchronize the execution of 
processes and threads. For example, if a process A needs to wait for the output of 
another process B, which needs to wait on the output of some other process C, 
there must be some way of synchronizing their execution: first C, then B, then A. 
Generally the programmer uses a combination of both interprocess communica- 
tion and execution control functions to implement this synchronization. Gener- 
ally, too, as in any programming problem, there is more than one viable solution. 

Unfortunately the subject of interprocess communication and execution con- 
trol and its relationship to writing applications for OS/2 is too complicated to 
come off well in a gloss. Chapters 2 and 3 discuss these topics in exhaustive detail. 
At this time we only wish to point out the way in which OS/2 has liberated 


* This concept will be fully explored in Chapter 3. It has only been introduced here to illustrate a point.. 
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programmers from writing code that executes in a sequential manner (first A then 
B then C), to allow them to write code that executes simultaneously. This 
introduces the factor of time into the coding processes in a way that seldom 
cropped up in a single-tasking system. To take full advantage of the power and 
performance of multitasking, applications have to be written as a number of 
separate cooperating tasks which work together to solve a whole problem. Need- 
less to say this has a tremendous impact on programming style. For programmers 
arriving at OS/2 from the microcomputing environment this is perhaps the 
biggest adjustment they have to make. Fortunately, OS/2 provides an adequate set 
of resources to meet such a challenge. 


The Relationship between OS/2 and DOS 


OS/2 is definitely the new applications platform for 286- and 386-based ma- 
chines. Buta gradual transition period is expected between the present time when 
DOS 2.x and 3.x applications are prevalent, to some future time when applications 
written especially for protected mode will prevail. OS/2 provides several features 
that will ease the pain involved in this transition for everyone. One of these is the 
compatability box, which allows a single DOS 3.x application to run as a special 
session in protected mode. Another feature that smooths the transition between 
a real mode and protected mode environment is the ability to create Family API 
Applications, which execute in protected mode, in OS/2’s compatability box, and 
also in the actual DOS 3.x environment. 


Compatability Box 


The compatibility box can be thought of as a special session which can be 
invoked from the Session Manager like any other. Asingle DOS 3.x application can 
be invoked from the compatibility box, and it interacts with the 80286 as if it were 
a real mode. At this time any protected mode applications running in the 
background will continue to receive processor cycles. The user can also use the 
Session Manager to switch out of the compatability box to bring any of the 
protected mode sessions into the foreground. When a compatibility box applica- 
tion is switched into the background, however, it does not receive any processor 
cycles. It remains idle until it is switched back into foreground. 

Most DOS 3.x applications will run in the compatibility box without modifica- 
tion. This is because an application running in the compatability box finds itself 
in a simulated DOS 3.x environment, complete with a copy of COMMAND.COM. 
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There are certain restrictions on compatability mode programs, however. For 
example, they cannot directly address devices, and they must restrict themselves to 
using documented DOS and BIOS calls. A detailed discussion of the compatability 
box is found in Chapter 21. 


Family API Applications 


Family API (FAPI) applications are applications that will run, without modifica- 
tion, in protected mode and the compatability box, as well as in an actual DOS 3.x 
environment. FAPI applications use the OS/2 API structure for requesting system 
services, but only a reduced set of these functions. The API functions that are not 
supported are those which make use of protected mode features, such as (among 
others) multitasking calls, interprocess communication calls, and dynamic link 
calls. However FAPI programs can take advantage of I/O, memory, and diagnostic 
calls that are applicable in the PC-DOS environment. 

An FAPI application is prepared in the same way as a protected mode applica- 
tion. The source files are written, compiled and the object modules are linked 
together. The resultant executable module is then executable in protected mode. 
In order to make this .EXE file executable in real mode as well, itis passed through 
the BIND utility. The BIND utility translates the OS/2 API functions into their 
corresponding PC-DOS and BIOS INT calls. 

The ability to create applications that run both in real mode and and protected 
mode will be a boon to developers wishing to maintain a commitment to the PC- 
DOS environment while looking ahead to the future. Unfortunately, programs 
designed to run in both modes will not be able to take advantage of the advanced 
features provided by OS/2. In Chapter 9, we discuss fully the issues pertaining to 
the creation of FAPI programs. In every chapter we discuss the restrictions placed 
on the use of an API function for Family API applications. 


Chapter 2 


Using Processes and Threads 


objects that are multitasked: processes and threads. We’ll discuss how to exploit 

multitasking capabilities with process and thread functions, and we'll learn the 
API functions needed to create and control processes and threads. 

With OS/2, PC programmers finally have an operating system that allows them 
to incorporate multiprogramming techniques in their applications. Having 
multiple sections of code execute asynchronously (at the same time) greatly 
increases the speed of applications when these sections implement a group of 
logically independent functions. For example, the editing, printing, and spell- 
checking functions of a word processor are completely independent of one 
another. There is no logical reason why a user should not continue to edit his 
document while running a spell-check, using the printing utility, managing the 
files on his drive, or even formatting a disk. Under DOS this is impossible since the 
operating system only attends to one function at a time. Even the casual user of 
word processors can be inconvenienced by such shortcomings. But with the advent 
of OS/2 and true multitasking capability on the PC, new applications designed to 
let functions that are independent of one another run asynchronously will become 
the norm. 

Multiprogramming is not only applicable for word processing, but for every 
application where several functions could go on at once. In a local area network 
(LAN) environment, the LAN file server provides services like file sharing, file 
serving, and print serving to a number of workstations. At any time there may be 
several requests by workstations for network services. To efficiently handle simul- 
taneous requests from its clients, a file server should be able to use the disk drive, 
printer, and the LAN adapter all at once. But without OS/2’s multitasking and 
protected mode capabilities a PC-DOS-based LAN file server is handicapped when 
it tries to provide these services for several clients. It must, for example, wait for 
the completion of an I/O operation before it can send data to the LAN adapter. 


| n Chapter 2, we introduce the basic concepts of multitasking, as well as the 
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With OS/2, one function can send/receive data to/from the LAN adapter, while 
another can access the hard drive. We can expect significantly faster file servers in 
the future. 

Our next example illustrates not only multiprogramming concepts, but other 
virtues inherent in the design of OS/2. Existing communications programs are 
plagued by the fact that DOS 3.x can only send and receive one character at a time 
to and from the communication ports. To make sure that no character is missed 
during high speed communication, a TSR program or an interrupt handler must 
be written to interrupt the CPU whenever a character is received. This character 
is then saved in a location in memory. The exact address of the location is known 
only by the TSR program and the calling program. This method is far from perfect, 
since, without memory protection, other programs can wipe out the buffer or 
disable all interrupts, preventing the proper handling of received characters. 
OS/2 solves this problem by providing automatic buffering in its asynchronous 
port device drivers. All received data is saved in a special buffer and protected. 

OS/2 communication programs can be divided into two processes. One 
process reads the communication ports and writes the received data into a pipe or 
queue. The second process reads the pipe or queue (see the following chapter on 
interprocess communication) and manipulates the data as needed. The OS/2 
programmer is freed from the burden of having to deal with interrupts, TSR 
programs, or the possibility of losing data during high speed communication. 

Processes and threads are both used to implement multitasking under OS/2, 
but they have their differences. Processes can be thought of as complete and in- 
dependent programs that can run simultaneously. An independent function that 
requires separate resources should be implemented as a process. To prevent the 
corruption of one process’s data by another, data shared between processes must 
go through the operating system. On the other hand, sharing data and resources 
between threads is natural; they can be thought of as separate procedures within 
the same program. In fact, threads are coded just like procedures within a 
program. Each thread, however, executes asynchronously from other threads. Say 
a process needs to obtain a list of the files and directories currently on a drive, and 
to display them in a user-friendly fashion on the monitor. Such a process can be 
divided into two threads: one that accesses the drive for files and directories and 
then saves the names in a buffer, the other paints the screen. When both threads 
finish, the primary thread can display the names stored in the buffer. 

Threads are used mainly to maximize the performance of a program when it 
accesses I/O devices. If a program has to wait for the completion of an I/O 
operation when communicating with a slow device (like a hard drive), the overall 
performance of the application may deteriorate. Under OS/2, an application can 
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create a separate thread to perform file manipulation or disk I/O. This thread 
executes independently, or asynchronously, from the primary thread. The 
primary thread, instead of waiting for the completion of I/O operations, can 
perform other functions such as receiving input from the user. 

It is common practice to divide a program into separate threads to handle I/O 
devices with different I/O rates. Each operation is completed in its own time, 
instead of being serialized one after another. For example, it is far more efficient 
to divide a program into three asynchronously executing threads—one that paints 
the screen, one that reads the asynch port, and one that writes to the hard drive— 
rather than implementing them as procedures that execute sequentially, first one, 
then the next, then the last. 


Processes 


As defined earlier, a process is a program executed by the user. The OS/2 
command processor, CMD.EXE, starts a process using the OS/2 function call 
DosExecPgm. When launching a process OS/2 allocates memory segments for the 
code, data, and stack of the program. The information required for memory 
allocation is stored in the executable file’s header. ‘The memory segments are then 
initialized with the contents of the program’s code, data, and stack, which are 
stored in the body of the program’s executable file. OS/2 then begins executing 
the program's code. 

At the start, a process has the following resources: a primary thread; code, data, 
and stack segments; and handles for standard input (STDIN) and standard output 
(STDOUT). During execution, the process acquires new resources through the 
allocation of memory; opening of files, pipes, semaphores, and queues; or the 
creation of new threads. 

Under OS/2, a process can create, or spawn, other processes, which are child 
processes. A child process can also spawn other processes—grandchild processes. The 
child process inherits all the resources owned by the parent process, unless 
specified otherwise by the parent process. A parent process, however, can only 
access additional resources aquired by a child with that child’s cooperation. 

A process is terminated when it calls the OS/2 function DosExit. A child process 
can be terminated by its parent process, or by OS/2 as the result of an unrecover- 
able error. When a parent process is terminated, all its children are terminated as 
well, unless the parent process specifies otherwise through parameters passed to 
the DosExit call. Any resources owned by a process are released once the process 
is terminated. 
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Process Resources 
At Start-up Time 


Primary Thread 
Standard I/O Handles 
Code, Stack and Data 
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Added during Execution 


Additional Threads 
System Resources: such 
as additional Device 
Handles, Pipes, Queues, 
Semephores, Shared 
Memory Segments etc. 





Figure 2.1 Process and thread resources. 


Threads 


Once a process starts, OS/2 creates a primary thread for the process. This 
primary thread can then create other threads which can, in turn, create more 
threads using the OS/2 function DosCreateThread. Thread execution can be 
suspended using the OS/2 function DosSuspendThread and execution can be 
resumed using DosResumeThread. All threads share access to the resources 
owned by the process to which they belong: global data, semaphores, open files, 
pipes, and queues. 

When deciding whether a thread has access to a particular system or process 
resource, or whether it can execute certain API functions applicable to the 
resource, the programmer should keep in mind that a thread has the same 
privilege as the process that created it. If a process is able to execute certain 
functions for manipulating a file, pipe, or semaphore, any thread created by that 
process can do the same. 
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The number of threads which can be started by a single process is 56. The 
default limit for the number of threads that can be simultaneously running in the 
entire system is originally 48; this limit can be raised to 255 threads using the 
parameter Threads in the config.sys file. If.the user wants to increase the ceiling 
on the number of threads to 70, Threads = 70 has to be specified in the config.sys 
file. OS/2 reserves 2K of memory for each thread specified in the Threads 
parameter. Installing more physical memory on the system allows a greater 
number of threads to run efficiently. 


Priority Levels 


At any given time, OS/2 can manage several processes, each of which can 
contain several threads, all of them contending for CPU cycles. If there is more 
than one ready thread, the OS/2 scheduler forms a queue where ready threads wait 
before execution. 

This ensures that CPU cycles are distributed among all the threads running in 
the system. However, not all operations require the same amount of CPU time. 
Certain crucial functions in an application, even an entire application, may require 
additional CPU cycles in order to perform adequately. To allow the programmer 
to specify the distribution of CPU cycles which allows for the execution of crucial 


Thread 


Priority 





Figure 2.2 OS/2 Scheduler (simplified). 
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tasks, OS/2 assigns a variable priority level to each thread active within the system. 
Threads with a higher priority level receive more CPU cycles from the OS/2 
scheduler. The priority level can be changed on a per-process or per-thread basis. 
A process or a thread can change its own priority level, or that of another process 
or thread. By manipulating their priority, crucial processes and threads can get the 
CPU cycles they need. OS/2, however, does not allow other processes and threads 
to wait longer than a predefined acceptable interval before being executed. 


Process Functions 


OS/2 provides many API functions that allow for the creation, termination, and 
synchronization of processes. 


Creating A Process 


To create a child process, the parent process calls the function DosExecPgm. 
When calling DosExecPgm, OS/2 expects the parent process to provide parame- 
ters specifying whether the child process will be executed asynchronously, inde- 
pendently of the parent process, or synchronously (the parent process waits for the 
completion of the child process). If the asynchronous mode is chosen, OS/2 
assigns a process ID (PID) to the child process and returns this value to the parent 
process. The child process obtains its PID using the function DosGetPid. The 
parent process can use the PID to coordinate its execution with the child process's. 
It can abort the child’s execution (using DosKillProcess), or it can halt its own 
execution to wait for the termination of the child process (using DosCWait). Any 
process can terminate itself using DosExit. The child process might also be aborted 
by OS/2 as a result of a hardware error or a protection trap. 

Child processes and threads are considered system resources. As a finite 
resource handler, OS/2 only handles up to 255 processes and 255 threads at the 
same time for the whole system. This means that from all the running applications, 
no more than 255 processes and 255 threads can be created. The recommended 
maximum for a single application is 12 processes and 12 threads. Unless an 
application is to run in a dedicated system this recommended limit should not be 
exceeded out of consideration for other applications the user may run under 
OS/2 at the same time. 

Child processes spawned by a parent process are considered to be running 
within the same screen group, or session. If the child process is set to execute 
asynchronously from its parent then it begins its execution in the background. If 
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itis set to execute synchronously it becomes the new foreground process within the 
session. Recall that background processes cannot receive input from the keyboard 
or the mouse. To receive keyboard or mouse input a process must be switched into 
the foreground. (See Chapter 12 for a full discussion of these matters.) However, 
all processes within a screen group can manipulate the same virtual video screen. 
A major issue in the relationship between a parent and child process is the way the 
video screen will be shared between them. The coordination needed to do this 
without corrupting the display must be established by the programmer. Since the 
parent and child process are cooperating for a specific purpose in the application, 
the programmer must consider the problems involved in sharing control of the 
video display, as well as I/O requirements of child processes. The API functions 
which enable coordination are discussed in future chapters. 


Process Start-Up Conventions 


When a child process is loaded into memory, it follows the same program start- 
up conventions it would if the program were executed from the command prompt. 
The program start-up convention for OS/2 contains no program segment prefix 
(PSP') as did DOS applications. When the program begins executing, it receives 
two pointers. One points to a memory buffer containing the environment block 
and the other points to the parameters related to the program. Both pointers are 
obtained by the process using the function DosGetEnv. Both memory blocks are 
located next to each other in memory as indicated in figure 2.3. 


ENnvPtr a TMP=C\TMP Q| Program Environment 
LINK=LIN 


PgmPtr > D\C\TEST.EXE Program Parameters 
TEST.EXE 






1011,100 


Figure 2.3 Environment block, program pointer, and arguments 


'PSPs are used by DOS to hold values for the interrupt vectors and FCBs. They are not applicable under OS/2. 
4 Pp 7 PP 
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The environment block consists of a series of ASCIIZ strings terminated by a 
null byte, followed by another NULL byte. Each string represents a variable and 
its value as specified by the SET commands. The format of the ASCIIZ string is: 


parameter=value<NULL> 


Parameter represents the variable name and value should be an ASCIIZ string. 
The value of any environment variable name can be determined using the function 
DosScanEnv. If the user issued the following OS/2 SET commands, 


SET COMSPEC=C:\0S2\CMD. EXE 
SET TEST=TEST VALUE 


the environment string would contain the two parameters previously set in the 
form of an ASCIIZ string: 


ASCIIZ string 1 


COMSPEC=C: \OS2\CMD.EXE<NULL> 
TEST=TEST VALUEXNULL> 


Last ASCIIZ string 
<NULL> 


The program parameter block consists of three ASCIIZ strings. The first string 
is the program pointer which contains the program name including the drive letter 
and the directory path. The next two ASCIIZ strings contain the two arguments 
for the program. The first argument simply contains the program name in the 
same way it was specified when the program was loaded by DosExecPgm or when 
it was executed at the command prompt. The second argument contains all the 
parameters passed to the program via DosExecPgm or as entered at the command 
line. 

Suppose the user is in the default directory, C\TEST, and enters the following 
command, 


code\pgmname parml parm2 parm3 parm4 
The program pointer contains the string: 


C: \TEST\CODE\PGMNAME. EXE 
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The first argument is: 
code\pgmname 

and the second argument Is: 
parml parm2 parm3 parm4 


C compilers also provide facilities to handle parameters passed to a program via 
variables argc, and argu/]. The compiler passes the program name as the first 
argument, but it automaticaly parses the second argument into several parameters. 
For example, the previous command line would be parsed into the following: 


argc =P 5 

argv -> “code\pgmname\0 parml parm2 parm3 parm4” 
arev([1] “> “parm” \* 0 ie @ NULL byte *4 
atev (2! =) “pari2™ 

arey|3 | -* “pjarm3” 

argv [4] -2) “parm” 


System Resources Inherited by a Child Process 


Using the function DosExecPgm, the parent process can pass arguments to a 
child process, and also control its environment block. 

The environment block is maintained by OS/2 and is given to the parent 
process by the command processor “CMD.EXE.” It can be used to pass any kind 
of information to the child process, but its intended purpose is to pass configura- 
tion information. A new set of environment arguments can be created by the 
parent process and passed to the child process. If no new environment block is 
passed, the child process automatically inherits the environment block of the 
parent process. 

The child process has its own LDT. It also inherits all the system resources 
opened by the parent process: file handles, pipes, queues, and semaphores, but not 
with the same access rights. (Refer to individual functions for their exact 


34 Advanced Programmer's Guide to OS/2 


specifications in inheritance of files, pipes, queues, and semaphores.) The 
inheritance of opened file handles allows the parent process control over the 
standard input and output of the child process. If the parent process opens one 
file as STDIN and another as STDOUT, the child process reads and writes to these 
files as if it is accessing the keyboard and the video display. 

There are no facilities which a child process can use to find out about its 
inherited resources. OS/2 assumes that parent and child processes are tightly 
coupled programs (programs cooperating closely with each other). Therefore, 
the programmer must know in advance what resources each child process will 
inherit. Though they are unneccessary in most cases, this lack of facilities for 
determining inherited resources is a shortcoming on the part of OS/2. 

A child process can, however, use several functions to get information about the 
system environment. It can obtain any arguments passed to it and the contents of 
the environment block using DosGetEnv. Other information can be obtained with 
functions like DosGetPID (which returns the PID of the calling process) and Dos- 
GetInfoSeg (which returns information of interest to every process within the 
system, as well as information pertaining only to the process calling the function). 
These functions are discussed on pages 38-47. A child process can also determine 
the device represented by a file handle (i.e., whether it represents a file, a device, 
or a pipe) with the function DosQHandType. See Chapter 5. 


DosExecPgm 


DosExecPgm creates a child process or executes another program. The child 
process runs synchronously with the parent process, or asynchronously. DosExec- 
Pgm can also create a detached process which runs in the background and does not 
inherit any resources from the parent process. 

If the child process is running in synchronous mode, the parent process’ 
execution is halted until the child process completes its own execution. If the 
asynchronous mode is chosen for the child process, DosExecPgm returns a PID, 
which is used for other process control functions. 

Creating a child process is the same as executing another program. Accord- 
ingly, the file name containing the program must be specified, including the drive 
and the path of the file name. The program’s name is specified by the parameter 
PomName. 

DosExecPgm also allows the parent process to pass arguments—as well as the 
environment string—to the child process with the parameters ArgPtr and EnvPir 
respectively. The child process can retrieve the environment string using the API 
function DosGetEnv (p.60). To receive the arguments automatically the child 
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process should declare the main() procedure to be: 


main (argc, argv, envp) 


PU alps argc; 
char Yarcy |. ls /* araument pointers */ 
char *envp[]; /* environment pointer to be 


received */ 


The sending process must adhere strictly to the required format for passing 
both the environment and any arguments. The argument string must have the 
following format: 


arepte <= “foo \Warel are? are? \0* 


where the word foo represents the program name and terminated with a null char- 
acter. The arguments argl, arg2, arg3 represent the first argument, the second, 
and third arguments respectively. 

The child process receives the arguments in the following format: 


argv -> “foo\0arel ere? ared\0" 
argv[1] “~ “epel” 
argv[2] of “awe n” 
argv [3] a ame 2 =< tol 


which means that the variable argv|1] points to the string “arg1”, and so on. 
The environment string must look like this: 


envptr <- “valiel = test] \Ovalue2 = test2\0"., 


The first environment variable is specified as “valuel = testl\0” with a null ter- 
minator. The second environment variable is “value? = test2\0,” also with a null 
terminator. Each environment variable must be terminated with a null. 

The receiving process receives the environment string in the following format: 


envp -> “valuel = test] \O0value2 = test2\0” 
envp [1] -> “valuel = test1\0” 
envp [2] -> ‘“value2 = test2\0” 


which shows that the variable envp/I/ pointing to a null terminated string “valuel 
= testl”, and so on. 

The parent process can also create a detached process with DosExecPgm. 
Issuing DosExecPgm with the detach option has the same effect as issuing the 
OS/2 Detach command at the OS/2 prompt. A detached process runs asynchro- 
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nously with the parent process, but does not inherit any resources owned by the 
parent process which created it. 

Like a child process, a detached process should not immediately expect any 
keyboard input from the user because it is running in the background. A detached 
process differs from a normal background process in that it cannot be switched 
into the foreground. Detached processes are used to implement TSR type 
programs and device monitors. To receive keyboard input, a detached process 
should use the OS/2 device monitor functions that monitor the device character 
stream. When the appropriate key sequences are entered, the detached process 
can pop up into the foreground, taking over the screen and keyboard. We will 
discuss implementing device monitors and pop-up processes in Chapters 16 and 
20. 

If the result codes of the child process are not expected, the parameter ExecMode 
should be set to zero or one. If the value is set to two or three, OS/2 takes up some 
memory to maintain the uncollected result code. OS/2 only gets rid of this 
memory when DosCWait is called. ‘The result code is then returned to the parent 
process. The termination code of a process is furnished by OS/2 to inform the 
parent process of the termination condition of the child process. 


DosExecPgm (ObjNameBufAdr, ObjNameBufLen, Execmode, 
Argptr, Envptr, RetCode, PgmName ) 


char far *ObjNameBufAdr; /* Pointer to a buffer with debugging 
info */ 
unsigned ObjNameBufLen; /* length of buffer ObjNameBufAdr */ 
unsigned Execmode; /* execution mode of child process */ 
char far *Argptr; /* pointer to arguments for child */ 
char far *Envptr; /* pointer to enviroment block */ 
struct ResultCodes far *RetCode; /* pointer for return code of child */ 
char far *PgmName; /* pointer to fully qualified name of 


child*/ 
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Compatibility Mode Restriction 


In the compatibility mode, the child process can be run only synchronously, not 
asynchronously. Therefore, when ExecMode is set to | or 2, DosExecPgm returns 
a “Could Not Execute” error. The parameter TermCode_PID is always 0. OS/2 
doesn’t assign a PID to the child process. 


Example 
j* EXEC.GC 
PARENT: NONE 


CHILD: CHILD.C 
This program demonstrates 


how to spawn another process using DosExecPgm 
set up argument strings 

set up environment pointer. 

Use DosExit to terminate a process. 
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Argument string must have the following format: 


* 


char "arg; 
argOQ <— “Child Program Name\0” must be null terminated 


argl arg2 arg3 etc <— must be in the same ASCIIZ string 
separate by space 


i.e area <= “CHILD. EXE \Oarel are? are3\0")s 
Environment string must have the following format 
envp1<CR> ; each environment string must have 
envp2<CR> ; the formst of <VARIABLE>=<STRING> 
sa ; t.e. TEST=TEST ENV 
envpn<NULL> 
ay 


include “doscalls.h” 
include “stdio.h” 


/* Values for execution mode, Execmode */ 


define SYNC 0 /* Synchronous execution */ 

#tdefine ASYNC 1 /* Asynchronous execution */ 

#tdefine ASYNC_RES 2 /* Same as 1, result eodes is returned */ 
main() 


{ 
/* Arguments for DOSEXECPGM */ 


char *ObjNameBufAdr ; /* Failed Object Name */ 

unsigned ObjNameBufLen; /* Object Name Length */ 

unsigned ExecMode; /* Execution mode of the 
child process */ 

struct ResultCodes RetCode; /* Reswlt Codes */ 

char *“Envptr: 

char PgmName[12]; y* Child program’s Name af 

ObjNameBufAdr = (char *)0; /* Should be set to Null */ 


ObjNameBufLen 0; 


4? Advanced Programmer's Guide to OS/2 


strcepy (PemName, ”"child.exe”) ; 
DOSEXECPGM ((char far *)ObjNameBufAdr, 
ObjNameBufLen, 
ASYNC_RES, /* asynchronous execution */ 
(chat far *)"child.exe\Qarel arg2 are3\0", 
/* areuments */ 
(char far *)*TESTENV=TESTVALUE\OTEST2=TEST2\0", 
/* envp */ : 
(struct ResultCodes far *)&RetCode, 
(char far *)PgmName) ; 


printt("\n The child process ID is : %d”,RetCode. 
TermCode_PID); 


DOSEXIT(1,0): 


f* CHILD, ¢C 

PARENT: EXEC.C 
CHILD: NONE 

* 


include <stdio.h> 
#Finclude <doscalls.h> 


ttdefine EXIT THREAD 0 
#tdefine EXIT_ALLTHREAD 1 


main(argc,argv,envp) 
int arec; 

ghar “arey (| : 

char *envp[]; 


{ 
printf(“\nThe number of arguments: %d”,argce); 


print’ (*\ndeeument 1: te” ,arev [1] 


23 
orintt (“\oAroument 2: Ys", arey([2Z)]); 


Using Processes and Threads 43 


Srincr ( Wikavironment string 2: ws", senvpli)); 
printf (“\nEnvironment, string 1: %se”",envp[0]): 
/* gll threads will end */ 
/* dummy return code to parent */ 


DOSEXIT(EXIT_ALLTHREAD, 20); 


Ending Processes and DosExit 


Every OS/2 process must use the function call DosExit to terminate its execu- 
tion. Threads can also use DosExit for termination though they aren't required to 
do so (the current version of the C compiler, however, requires that a C thread call 
DosExit to terminate). When a process terminates, all its resources are closed, and 
all opened file buffers are flushed. The terminating process can use DosExit to 
send a completion code to other processes currently waiting (using DosCWait) for 
its termination. 

A process can set up routines to clean up its resources before termination by 
using the function DosExitList. When using DosExitList, all threads belonging to 
the process are terminated except for the primary thread, which is used to execute 
the routines specified in DosExitList. 


DosExit (ActionCode,ResultCode) 


unsigned ActionCode; /* termination request type */ 


unsigned ResultCode; /* value sent to waiting processes */ 
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Compatibility Mode Restriction 


There are no threads in the compatibility mode. OS/2 simply terminates the 
program. If ActionCode = 0, this value is ignored. 


DosExitList 


If a process terminates using DosExit, all the threads owned by this process are 
also terminated. To prevent hanging threads, the corruption of data when a thread 
abruptly terminates, a process can use the function DosExitList to set up routines 
which are run before actual termination. Use DosExitList to set up routines that 
clear opened semaphores, deallocate shared memory, and generally allow for an 
orderly termination of the process. Library modules use this function to free their 
resources and clear semaphores and flags in the case of an abrupt termination by 
the running process. 

DosExitList provides three possible options which: (1) add a termination 
routine to the termination list, (2) remove a routine from the termination list, and 
(3) allow a termination routine to notify OS/2 that it has completed processing 
(this option instructs OS/2 to execute the next routine on the termination list). 
Multiple termination routines are defined by calling DosExitList, with the first 
option, multiple times. 
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When the process issues DosExit, OS/2 destroys all other threads except the 
primary thread. OS/2 then executes one of the termination routines previously 
specified using option | of DosExitList. Each routine on the termination list must 
call DosExitList with option 3 before terminating so OS/2 can transfer control to 
the next termination routine. The transfer of control to each termination routine 
does not follow any particular order. But OS/2 does execute each routine on the 
termination list. Remember, if a routine in the termination list does not issue 
DosExitList with option 3 before terminating itself, the process is placed in an 
indeterminate state. 

The programmer should remember that the termination routine is executing 
in a State of partial termination. All other threads have been terminated. Only the 
primary thread is active during the execution of the termination routines. To 
guarantee minimum delay in terminating a process, the termination routines 
should be quick and fail-safe. They should not call any functions that might fail. 
Most OS/2 API calls are valid in a termination routine except for DosCreateThread, 
DosExecPgm or other functions involving threads or processes. ‘The termination 
routine should not wait for a semaphore or the completion of another process. 


DosExitList (Function_code,Proc_Adr) 


unsigned Function_code; /* DosExitList option */ 


void (far *) Proc_Adr; /* address if termination routine */ 
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Example 
f* BSTTListT.c 


This program demonstrates how 


my 


include “doscalls.h” 


4tdefine TERM ADD 1 
dEdefine TERM REMOVE 2 
4tdefine TERM DONE 3 
4tdefine EXIT THREAD 0 


4tdefine EXIT _ALLTHREAD 1 


"Old far tearm _routl()3 
void far term _rout2(): 


main() 


{ 


unsigned ret; 


/* 


to 


/* 
/* 
/* 
/* 


ise BDoskeithist. 


DOSEXITLIST, function code 
add termination routine */ 
remove termination routine 
done executing termination 
routine */ 


add term_routl and term_rout2 to the termination 
routine list */ 


ae 


at | 
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ret =— DOSEXITLIST(TERM ADD, term rowtl) ; 
Lf (ret) 
print? ("\nDesExitlist 1 failed: “Md” ,ret). 


ret= DOSEXITLIST(TERM ADD, term rout2): 
iF (ret) 
printf(“\nDosExitList 2 failed: %d”,ret); 


DOSEXIT(EXIT THREAD, 0); 


/* termination routine 1 */ 


Wold far term routl() 
{ 
printi(“\nThie 16 termination routine 1”): 
/* need to tell OS/2 that routine is done */ 
DOSEXITLIST(TERM DONE, (char *)0); 


} 
/* termination routine 2 */ 


void far term rout? () 


{ 
printfi(“\nThis is termination routine 2”) ; 
/* need to tell OS/2 that rotitine ig done */ 


DOSEXITLIST(TERM DONE, (char *)0O); 


Terminating Another Process Using DoskKillProcess 


A process can terminate the execution of other processes using the function 
DosKillProcess. Any process currently waiting for the terminated process with 
DosCWait receives an abnormal termination code. DoskKillProcess is intended to be 
used by a parent process for terminating its child processes. The process ID, PD, 
supplied to the parent process by the function DosExecPgm, is required to 
terminate the child process. Any process, however, can be terminated if its PID is 
known. Since the PID is only an integer variable, any OS/2 process can be 
terminated, even the OS/2 Session Manager or the OS/2 command processor, 
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CMD.EXE. Ifa crucial OS/2 process is killed, the system goes into an indetermi- 
nate state and it is necessary to reboot. To prevent inadvertent corruption of the 
system, applications should use only the PID returned by DosExecPgm to kill child 
processes. 

RAM semaphores owned by a process will not be freed if the process was 
terminated abnormally by DosKillProcess. Data buffers managed by the process, 
such as internal buffers utilized by C libraries, will also not be flushed. An 
abnormally terminated process can be left in an indeterminate state. Therefore, 
an application should use DosKillProcess only as a last recourse when it wants to 
terminate a child process. 

A running process can prevent the untimely interruption of its execution by 
using the function DosSetSigHandler (refer to Chapter 8) to notify itself of 
termination attempt by another process. Once the termination attempt is 
detected, the running process can close open files, pipes, queues, semaphores, and 
other resources and use the function DosExit for a proper termination. The 
running process, however, should not use the DosSetSigHandler function to 
ignore termination attempts. When DosKillProcess is used, the application should 
incorporate DosSetSigHandler in the running process to release system resources 
as a safety measure in case of abnormal termination. 

When the running process does not use DosSetSigHandler to notify itself of a 
termination attempt, OS/2 goes ahead and terminates the process. All handles 
of opened files, pipes, queues, and system semaphores owned by the process— 
except for RAM semaphores and internal data buffers— are closed. 


DosKillProcess (ActionCode,PID) 


unsigned ActionCode; /* Type of termination */ 


unsigned PID; /* PID of target process */ 
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Example 
/* KILLP2.C 


PARENT: KILLP.C 
CHILD: NONE 
F 


include <stdio.h> 
include <doscalls.h> 


+#define EXIT THREAD 0 
4Hdefine EXIT ALLTHREAD 1 


main(argc,argv,envp) 
Lic Bare: 

char *arav[]: 

char *envp[]; 


{ 
printf(“\nThe number of arguments: %d”,argc); 


orintt®(“\Areument 1: %e”,.arevilil): 
printt (*\nArgument 2: %s”,arev[2]); 
ptinti ("\nEnvironment string 2: %s",envp[i)): 
Heit’ (* inEnvironment tring i+ %s”,envo [0] ): 

/* all threads will end */ 

/* dummy return code to parent */ 
DOSSLEEP(5000L) +s 


DOSEXIT(EXIT_ALLTHREAD, 20); 


50 Advanced Programmer's Guide to OS/2 


/* KILLP.C 
PARENT: NONE 
CHILD: RILLE?.C 


This program demonstrates how to use DosKillProcess to terminate 
A child process. 


“f 


include “doscalls.h” 
Finclude “stdic.h” 


/* Values for execution mode, Execmode */ 


#tdefine SYNC O /* Synchronous execution */ 

#tdefine ASYNC 1 /* Asynchronous execution */ 

+#define ASYNC_RES 2 /* Same as 1, result codes is returned */ 
4define ONLY PID 1 /* action code of DosKillProcess */ 
/t}define ALL_CHILDPID 0 

main() 


{ 
/* Arguments for DOSEXECPGM */ 
ehar *ObjNameBufAdr; /*® Failed Object Name */ 
struct ResultCodes RetCode; /* Result Codes */ 


char *Envptr; 
char PgemName [12]; /* Child program’s Name */ 


unsigned ret; 


strepy (PgmName, ”killp2.exe”); 
DOSEXECPGM ((char far *)0O, 
Og 
ASYNC_RES, /* asynchronous execution * 
(char far *“)"killp2.exe\Oarel are? arg3\0", 
/* arguments */ 
(char far *)”TESTENV=TESTVALUE\OTEST2=TEST2\0", 
/* enyp oF 
(struct ResultCodes far *)&RetCode, 
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(char far *)PgmName) ; 


erintt(“\o The child process ID is ¢ 2d”, RetGoda.Termode PID): 
if (ret= DOSKILLPROCESS (ONLY_PID,RetCode.TermCode_PID) ) 
orint®t(“\nDoskillProcess failed: %d”. ret): 


DOSEXIT(1,0); 


Synchronization between Processes: DosCWait 


OS/2 provides the function DosCWait for synchronization of a running process 
with another asynchronously executing process. DosCWait is used when the com- 
pletion of one process is crucial for the execution of another process. For example, 
in downloading files from the mainframe to the micro, one process can be 
receiving the file, and another can translate the data into a PC format. The 
receiving process can be asynchronously executing, while the parent process asks 
the user to identify the file’s path, name, and other initialization tasks. The parent 
process then waits for the completion of the receiving process to execute the 
translating process. 

DosCWait causes the current thread to wait until the completion of an asynchro- 
nous process specified by the process ID (previously supplied to the parent process 
in the return of the function DosExecPgm), then returns the process ID and the 
termination code of the process being waited on. The function DosCWait has 
several waiting options: 

= The current thread waits until the process specified by PID 


# The current thread waits for any child process to end. 


= The current thread waits until all the processes owned by the child process 
specified by PID stop. This option, however, requires that DosCWait be 
called repeatedly for each process owned by the PID. 


DosCWait (ActionCode, WaitOption, Ret_Code, Result_PID, PID) 


unsigned ActionCode; /* type of process to wait for */ 
unsigned WaitOption; /* waiting option */ 

struct Resultcodes far *RetCode; /* return codes from target */ 
unsigned far *Result_PID; /* PID of terminated process */ 


unsigned PID; /* PID of target process */ 


52 Advanced Programmer's Guide to OS/2 





ActionCodeand WaitOptioncombined specify the waiting condition of Dos CWait. 
The following summarizes every possible option. The programmer should experi- 
ment with different options for a better understanding of the intricacies involved. 
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The termination code of a process is furnished by OS/2 to inform the process 
performing DosCWait of the termination condition of the child process. The 
following lists the termination code values and their meanings: 





The result code is a value sent by the child process to the parent process using 
DosExit. 
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Compatibility Mode Restriction 


The functions of DosCWait are not applicable in the compatibility mode since 
no child process is allowed to run asynchronously. 
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Example 

/* GCWAIT.C 

PARENT: NONE 
CHILD: CWAIT2.EXE 


All four possible waiting options of DOSCWAIT will be demon- 


strated in this program. Please examine carefully the result 
displayed by the program. 
ey 


include “doscalls.h” 
include “stdio.h” 


4tdefine SYNC 0 
d4tedefine ASYNC 1 
4tdefine ASYNC RES 2 


main() 
{ 
Struct ResultCodes child status, RetCode:; 
unsigned Result_PID, RES; 
ehar *ehild envy; 
char PgmName [30] ; 


/* Beeeute the child process */ 


strcepy (PgmName, ”CWAIT2.EXE”) ; 
DOSEXECPGM( (char far *)0, 
QO, 
ASYNG _RES, 
(char far *)0, 
(ehar far *)0, 
(struct ResultCodes far *)&RetCode, 
(char far *)PgmName) ; 


printf(“\nChild Process’s PID = %u\n”, RetCode. 
TermCode_PID) ; 


/* Wait for child process te finish */ 
/* actioncode = 0, waitoption = 0 */ 
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DOSCWAIT (0, 
QO, 
(struct ResultGodes far *) &child status, 
(unsigned far *) &Result_PID, 
RetCode.TermCoda_ PID); 


if (child_status.TermCode_PID != 0) 
printf(“ERRROR: “Yu. Unusual termination. \n”, 
child_status.TermCode_PID) ; 
else 
printf(“\nchild process %u stopped”, 
ehiid status .ExitCode) ; 


/* Execute the child process */ 


DOSEXECPGM( (char far *)0, 
dy 
ASYNC _RES., 
(char far *)6, 
(¢har far * 16, 
(struct ResultCodes far *)&RetCode, 
(char far *)PgmName) ; 
printf(“\nChild Process’s PID = %u”, RetCode.TermCode_PID; 


/* Wait fer the complétion of the FID and all of its deecen- 
dants. Need to issue a DOSCWAIT for each process to be wait 
upon. 
fd 
do { 
/* Actioncode = 1, WaitOption =0 */ 
RES = DOSCWAIT( 
Ih 
O 
(struct ResultCodes far *)&child_status, 
(unsigned far *)&Result_PID, 
RetCode.TermCode_PID) ; 


/* when there’s no more running process */ 
/* O8/2 veturne an error */ 

LECRES == 0) 
printf (“\nPID = %u stopped”, Reeult_PID): 
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else 


printf(“no more running process\n”); 
} while (RES != 0); 


/* Execute the ehild process */ 


DOSEXECPGM( (char far *)0, 
i, 
ASYNC_RES, 
ichar far *)], 
(ehar far *)0, 
(struct ResultCodes far *)&RetCode, 
(char far *)PgmName) ; 


printf(“\nChild Process’s PID = %u”, RetCode.TermCode_PID; 


/* check if any process owned by the PID or the PID itself 
have terminated. This section of code will continue 
checking until one process stopped. */ 


do { 
RES = DOSCWAIT ( 
ly /* aetion code = 1 */ 
l, /* wait option = 1 *7 


(struct ResultGodes far *)é&child etatus, 
(unsigned far *)&Result_PID, 
RetCode.TernCode. PID) : 

if (RES==0) 


printf(“\nchild %u ended”,Result_PID) ; 
else | 


print’ (“Ne child process stopped, error Yuin", RES) ; 
|} while (RES = 0); 


/* Execute the child process */ 


DOSEXECPGM( (char far *)0, 


O, 

AS YNG-RES . 

(char far *)0, 

(cher Far “30, 

(struct ResultCodes far *)&RetCode, 
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(char far *)PgmName) ; 


printt(“\nChild Preeess*s PID = %u", RetCode.TermCode PID: 
/* In this section, the PID specified is 0. Program waits 


for termination of any child process owned by the 
calling process */ 


do { 
RES = DOSCWAIT ( 
1, /* action code = 1 */ 
0, /* wait option = G-*/ 
\Sttuct ResultCodes far *)&child status, 
&Result_PID, 
GO): /* Any child process */ 
if (RES =— 0) 
printt(" \nehiid %u eanded’, Result PID) : 
} while (RES == 0); 


DOSES IT (1, 0) : 


f* GWATT2 .C 


PARENT: CWAIT.C 
CHILD: NONE 
a 


include <doscalls.h> 


4tdefine EXIT THREAD 0 
4tdefine EXIT ALLTHREAD 1 
main() 


{ 


DOSEXIT (EXIT ALLTHREAD, 20): 
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Process Information Functions 


In addition to the API functions OS/2 provides for the creation, destruction, 
and synchronization of processes, there is another set of API functions that can be 
used by a process to find out about its execution environment. The function 
DosGetEnv is used by a process to obtain the environment block inherited from its 
parent. DosScanEnv scans that block for the value of a particular parameter. 
DosGetPID determines its process ID. DosGetInfoSeg returns a variety of informa- 
tion stored in the GDT, available to all processes, and in the LDT, pertaining to that 
process alone. DosGetVersion returns the version number of the operating 
system. DosGetMachineMode tells the process whether it is operating in real or 
protected mode. 


DosGetEnv 


DosGetEnv returns a pointer to the environment table inherited by the calling 
process. The environment table is either inherited from the parent process, if it 
was launched via DosExecPgm, or from the command processor, if the process was 
started from the OS/2 command line. As discussed on page 34, a child’s environ- 
ment block can be changed by the parent process. If the parent process did not 
change the environment block, the child process inherits the parent’s environ- 
ment block. The environment block contains both the environment string as 
defined by the previous SET commands and the program arguments as specified 
by the user at the command line or by the parent process. 

The function DosGetEnv returns two values: the selector of the environment 
block—EnvSeg, and an offset within this block where the command line argu- 
ments passed to the program are stored—CmdOffset. The environment parame- 
ters start immediately at offset OOOOH within the block defined by the returned 
selector. Recall that every memory location in the 80286 is referenced bya selector 
and an offset in the format of selector:offset. Both selector and offset are two bytes 
long. 

DosGetEnv expects two parameters: pointers to two unsigned variables where 
the selector of the environment block is returned, and an offset within that block. 
These specify the location where the parameters from the command line are 
stored. Remember that the values returned are only unsigned (2 byte) values. To 
make these into valid memory addresses, the program needs to recast them into 
32-bit pointers. For example, 
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char *EnvPtr: /* Pointer to environment block */ 

char *CmdPtr: /* Pointer to parameter */ 

unsigned EnvSeg; /* Parameters to be passed to Dos 
GetEny */ 


unsigned CmdOffset; 
DosGetEnv (&EnvSeg,&CmdOffset); /* Call DosGetEnv with 
the two pointers */ 


To use the returned values to access the environment block the program needs 
to recast them into 32-bit pointers or FAR char pointers. 


/* eonvert into lone then shift 16 bite left */ 
/* or multiply the value with 64K that would be 
slower */ 
EnvPtr = (char *) (long)EnvGSes << 16): 
GmdPtr = (char *}(anvPte + CmdOfiset) ; 
/* add offset to get starting address of command line 
arguments */ 


DosGetEnv (EnvSeg,CmdOffset) 


unsigned far *EnvSeg; /* selector of the environment block */ 


unsigned far *CmdOffset; /* offset where the command line 
arguments start */ 
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Example 
/* GETENV.C 


This program demonstrates how to use DosGetEnv. 


it | 
#include <doscalls.h> 


unsigned lstrlen(); 


main() 
{ 
char far “EnvPtr: /* pointer te environment block */ 
char far *OmdPtr: /* pointer to command line arguments */ 


char far *envl; /* pointer to first environment 
parameter */ 

char far *env2: /* point te second */ 

unsigned EnvSeg; /* selector of the environment block */ 


/* offset where the command line arguments start */ 
unsigned CmdOffset; 


DOSGETENV(&EnvSeg, &CmdOffset) ; /* get environmment 
parms */ 


/* gecast returned selector te 32 bit pointer */ 
EovPtr = (char far *) ((long)Envéee << 16); 

/* get pointer to command line arguments */ 
CmdPtr = (char far *) (EnvPtr + CmdOffset); 

/* display first environment string */ 


anvil = EnvPtr: 
printf£(“\nEnvironment parameter #1: %Fs”,envl); 


/* display second environment string */ 
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env2 = envl +tistrilen(envl)t1; 
printf(“\nEnvironment parameter #2: %Fs”,env2); 


/* display first command line argument */ 
printf(“\nCommand line argument #1: %Fs”,CmdPtr); 


printf(“\nCommand line argument #2: %Fs”, (CmdPtrt+lstrlen 


(CmdPtr)+1): 
/* the other command line arguments can be determine using 


the same method as EnvPtr */ 


unsigned lstrlen(s) 
char far *s; 


{ 
unsigned i=0; 
ehar Tar *t; 


oS es 
while {(*tt+ 1=— *\0°*) 


i Mag a a 
return (i) : 


DosScanEnv 


Function DosScanEnv searches through an environment table for a specific 
environment variable. DosScanEnv expects an ASCIIZ string buffer containing 
the parameter name (EnvVarName), and returns the memory address on the 
environment block of the parameter value (ResuliPointer). ‘The memory address 
will be a four-byte or long value in the form of selector:offset. 

As explained earlier, each environment variable is defined with the format of 
parameter=value. For example, if the environment block contains 


path=\ose2: bin 
and the process issues 
DosScanEnv (“path”,&ResultPointer) ; 


then a succesful completion returns ResultPointer, pointing to the string of 
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\os2+ \bin 
which is in the environment block. 
DosScanEnv (EnvVarName, ResultPointer) 


char far *EnvVarName; /* pointer to ASCIIZ string containing 
the environment variable name */ 


long far *ResultPointer; /* pointer to a four-byte value where the 
address of the environment value 
string is returned */ 





Example 
/* SCANENV.C 


This program demonstrates how to use DosScanEnv to search for 
environment variable value. 


This program will use DosScanEnv to obtain the value of the 
environment variable PATH. 


ef 
include “doscalls.h” 
main() 


{ 
ecHar tar *ResultButtfer: 
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unsigned ret; 


/* DosScanEnv expects an address of a far pointer The 
memory has already been allocated. It will simply 
assign *ResultBuffer to that memory location */ 


/* The program should be careful with the returned 
pointer. It should only be read from. Don’t write to 
the pointer, because you will change the value of the 
environment variable and you might overwrite other 
Variables, */ 


ret = DOSSCANENV (“PATH”, &ResultBuffer) ; 


if (ret) 
printf(“\nDosScanEnv failed: %d”,ret); 
else 
printf (*\nResultBuffer: %Fs”,ResultBuffer) ; 


DOSEXTT(1,0); 


DosGetPID 


DosGetPID returns the calling process PID, the calling thread ID, and the 
parent process PID. DosGetPID expects a pointer to a 6-byte data structure where 
the returned information is placed. The data structure has the format: 


struct ProclIdsArea { 
unsigned procid opid; /* process ID */ 
unsigned procid_ ctid: /* thread ID */ 
unsiened procid _ppid; /* parent PID */ 
i” thie eteueture as declared in 
dosealle.b *7 


DosGetPID (Id_Info) 


struct ProcIDsArea far *Id_Info; /* structure to the returned ID 
information */ 
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Example 


gitruct ProcidsAres ID Info: 
ret = DosGetPID( (struct ProciIDsArea far *) 87D Info): 


if (lret) | 
printé(“\nProcess. ID: %d",ID Tnfto.proecid_cpid); 
printt (“\nThread ID + “d", TD Inte.proeid_etid) : 
printf (“\nParent PID: %d”,ID_Info.procid_ppid) ; 


DosGetinfoSeg 


DosGetInfoSeg returns information of interest to every process within the 
system, as well as information that pertains only to the process which calls the 
function. This information is stored (respectively) in the Global Descriptor 
Segment and the Local Descriptor Segment. The Global Descriptor Segment is 
stored in the GDT, and a separate Local Descriptor Segment is kept in each 
process's LDT. 

The function DosGetInfoSeg expects two parameters, GlobalSegand LocalSeg, to 
which it returns pointers to the Global Descriptor and Local Descriptor segments. 
The information in these segments is constantly updated by OS/2. Thus, there is 
no need for a process to make repeated calls of DosGetInfoSeg to get fresh 
information. For example, the global descriptor segment contains the current 
date and time. A process that needs to monitor the passage of time does not need 
to call DosGetInfoSeg each time it needs to know the time. The process merely has 
to reference the appropriate field in the Global Descriptor Segment data struc- 
ture. 

The GlobalSeg parameter points to a data structure containing a variety of 
information: the current time and date, the version number of the operating 
system, current screen group ID, the maximum number of screen groups, the shift 
count for a huge segment, the current processor mode (protected or compatbility 
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mode), the PID of the current foreground process, and the OS/2 scheduler’s 
parameters. All of these parameters will not be discussed in detail here, but are 
explained in their appropriate place. 

The data structure for the Global Descriptor Segment is as follows: 


struct gdtinfoarea { 





unsigned long time; /* time From 01-01-1970 in 
seconds */ 
unsigned long milliseconds; /* and miliseconds */ 
unsigned char hours; j* Current time in hour, */ 
unsigned char minute; (/* minute, 77 
unsigned char seconds; /* geconds, */ 
unsigned char hundredths; /* and hundresths of second 
ed 
unsigned timezone; /* current time zone */ 
unsigned tinier interval: /* interval of timer */ 
unsigned char day; /* date information */ 
unsigned char month; 
unsigned year; 
unsigned char day_of_week; 
unsigned char major_version; /* OS/2 version # */ 
ingiened char minor version: /* eg. 3.la */ 
unsigned char revison_letter; 
/* system status info. */ 
unsigned char current_screen_group; /* current screent 
group # */ 
unsgined char max_num_of_screengrps; /* maximum number of 
screen group */ 
unsigned char huge_shift_count; /* shite seunt of 
huge seg */ 
unsigned char protected_mode_indicator; 
unsigned foreground_process_id;/* id of foreground 
: process */ 
unsigned char dynamic_variation_flag:/* scheduler 
parameter */ 
unsigned char maxwait; 
unsigned minimum_timeslice; 
unsigned maximum_timeslice; 
unsigned bootdrive; /* current boot drive */ 


unsgined 


} 


char 


trace _flag[32]; /* used for debugger */ 
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And the Local Descriptor Segment: 


struct ldtinfoarea { 

unsigned current_process_id; 

unsigned parent_id; 

unsigned priority_of_current_thread; 

unsigned thread_id_of_current_thread; 

unsigned screen_group; 

unsigned subscreen group; 

unsigned current_pid_in_fg; /* current process ID 
in the foreground*/ 


} 


To summarize, the date and time information includes the year, month, day, 
day of the week, hour, minute, second, and hundredth of a second when the 
function was called. Date and time information is also returned in terms of the 
number of seconds elapsed since 01-01, 1970. The time zone value represents the 
time-zone for which the system was configured using a parameter in the config.sys 
file, and is the difference in minutes between the current time-zone and Greenwich 
Mean Time (GMT). A positive number indicates that the time zone leads the GMT 
and a negative number indicates it lags behind GMT. For example, a system 
configured for eastern standard time would have a time?zone value of 300 minutes 
(or five hours) before GMT. 

The operating system version includes the major version number, the minor 
number, and the revision letter (e.g., version 3.1a where the major version number 
is 3, minor version number is | and the revision is “a”). 

The system status information includes the current screen group number, the 
maximun number of screen groups allowed, the protected mode indicator 
specifying whether the system is in protected mode (1) or compatibility mode (0), 
and the process ID of the current foreground process. This information will be 
explained in more detail in Chapter 9. The significance of the parameter shift 
count for huge segments is explained in Chapter 4. 

The scheduler parameters consist of dynamic variation flag status, the maxi- 
mum number of seconds a thread will wait before execution, the maximum time 
slice and the minimum time slice. These values are explained later in the chapter. 

The local descriptor information consists of the current process ID, the parent 
process ID, the priority of the current thread, the thread ID, the screen group 
number, the subscreen group number, and the PID of the process currently in the 
foreground of the session. DosGetInfo could be viewed as a function which returns 
all the information pertinent to a process and a thread. There are other functions 
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which return a subset of this information like DosGetPrty which returns the 
priority of the current thread, DosGetPID the PID of the calling process, or 
DosGetVersion the OS/2 version number, etc. 


DosGetinfoSeg (GlobalSeg, LocalSeg) 


struct gdtinfoarea far *GlobalSeg; /* structure for the global descriptor 
information */ 


struct ldtinfoarea far *LocalSeg; /* structure the local descriptor 
5 . Pp 
information */ 





DosGetVersion 


This function simply returns the version number of the operating system. It 
expects a pointer to a 2-byte variable where the version number will be stored by 
OS/2. The high byte of the value represents the major version number, and the 
low byte contains the minor version number. 


DosGetVersion (Version) 


unsigned far *Version; /* pointer to the variable */ 
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Example 
4+tKdefine LOBYTE(w) ((char) (w)) 
define HIBYTE(w) (( (unsigned) (w) >> 8) & Oxff) 


unsigned Version; 
DosGetVersion ((unsigned far *)&Version) ; 


prance (“\nVersion Number: %d.%d"., 
HIBYTE (Version) , LOBYTE(Version) ); 


DosGetMachineMode 


DosGetMachineMode returns the current operating mode of the system (i.e. 
whether it is in real or protected mode). The function expects a pointer to a 1-byte 
variable where a value will be returned. If this value is 1, then the system is in 
protected mode. The system is in real mode if the value is 0. 


DosGetMachineMode (Mode) 


char far *Mode; /* pointer to a variable where the mode 
value is returned */ 





Example 


char Mode; 


DosGetMachineMode ((char far *)&Mode) ; 
if (Mode) 

printft(“\nSystem is in protected mode.”); 
else 

printf(“\nSystem is in real mode.”); 
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Thread Functions 


OS/2 has a rich set of API functions giving applications the ability to create and 
terminate threads, to suspend and resume the execution of threads, and to 
manipulate threads’ priority. 


Create Threads 


As mentioned earlier, OS/2 creates a primary thread when a program is started. 
The primary thread can then create other threads, which in turn can create more 
threads using the function DosCreateThread. Only 255 threads are allowed within 
a process. The thread that issues the function DosCreateThread is termed the 
calling thread. Once created each thread is assigned a Thread ID. A thread can find 
out its ID using DosGetPid. 

In assembly language, a thread is just another procedure within the program’s 
code. First the calling thread has to set up memory for a new stack to be used by 
the new thread, then it has to call DosCreateThread providing it with an address 
where the new thread will begin its execution, and a pointer to the new stack. The 
thread can be terminated with the RET instruction or DosExit. 

There are a few restrictions using thread functions with the current Microsoft 
C Compiler v. 5: 


= A thread is just like a C function. The calling thread has to call 
DosCreateThread. With the address of the C function, and a pointer toa 
new stack. But the function cannot have any arguments. (It is possible to 
have arguments with a thread. The programmer, however, needs to know 

_ afew tricks in manipulating the stack with the current Ccompiler. We will 
demonstrate this technique in one of the example programs.) 


= All threads have to be terminated by calling DosExit. 


= A thread must use the C function melloc() to allocate memory for its stack 
if that thread calls any C run-time libraries that copy parameters from the 
stack. Other threads can use DosAllocSeg to allocate stack memory. 


= Since the 80826 stack grows down, malloc() sets up a pointer pointing to 
the bottom of the stack. The programmer must add the pointer with the 
stack size to have the correct stack pointer (see figure 2.4). 


= If a C function threads access global data, the programmer should use 
critical sections or semaphores (see Chapter 3) when changing the value 
of the global data to insure the data’s integrity. 
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Application must 
add the size of the 
stack (in bytes) to > 
the returned value 
in order to have 
proper SP value. 


High Memory 


Pointer returned by Low Memory 
malloc() points to 


wrong end of stack. 





Figure 2.4 Changing the stack pointer. 


All these quirks are expected to be removed with the next release of the C 
compiler from Microsoft. 

The calling thread has to set up a new stack with enough memory for proper 
execution of the new thread’s code. Each language compiler uses stack memory 
differently. With Clanguage compilers, every time a function (remember function 
and thread are equivalent) is called, the compiler uses stack memory to set up the 
memory required by the function variables (except those variables declared as 
static). If the function’s arrays and variables require 4K of memory, the compiler 
uses 4K of stack memory. To set up the appropriate stack size for a thread, the 
programmer must determine which function in the thread requires the most 
memory. The stack size should be equal to the requirement of the function that 
consumes the most memory. 

In assembly language, the programmer has complete control of how the 
memory is used, and can therefore easily determine the stack size. For other 
languages, consult your compiler manual. 

When the function DosCreateThread finishes, it returns a thread ID to the 
calling thread (the primary thread is automatically assigned thread ID number 
one). The calling thread can then use this ID for suspension and resumption of 
the new thread’s execution. This ID is also required when changing the thread’s 


priority. 
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The primary thread, Thread I, of each process is used by OS/2 as the signal 
handler. If thread 1 is suspended or somehow hangs, the process will not be able 
to handle special signals, and the program might be put in an undetermined state 
if a signal is sent to the process. Signals are used to inform the process of external 
events, i.e. if Control-Break was pressed by the user or if the process is being 
terminated by the parent process (see section on DosKillProcess). 

Since the execution of a thread is similar to the execution of another procedure 
within a program, a thread has access to all the resources and global memory 
variables owned by the process. ‘These resource include all the open file handles, 
pipes, queues, and semaphores. The only resources that are private to the 
individual thread are its stack and priority. 

A thread can end by using the 80286 instruction RET, just like a procedure. In 
C language applications a thread must use the function DosExit, with parameter 
ActionCode = 0, to terminate its execution (refer to page 43 for more informa- 
tion). 


DosCreateThread (Proc_Adr, Thread_ID, NewThreadStack) 


void (far *) Proc_adr; /* address of new thread */ 
unsigned far *Thread_ID; /* pointer to returned thread ID */ 
unsigned char far *NewIhreadStack; /* adress of the threads stack */ 
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Compatibility Mode Restriction 


This function is used in protected mode only. 


Example 
/* THREAD.C 


This example will demonstrate how to create thread with C, how 
to handle the stack and how to terminate thread 


af 


fHinclude “malloc.h” 
#Finclude “stdio.h” 
include “doscalls.h” 
include “subcalls.h” 


ttdefine STACK SIZE 1024 
wOoLd far thread? () : 


main(argc,argv) 
Lit Aree: 
chart *arayi[i: 
/* DOSCREATETHREAD arguments */ 


char far *new_stack; 
unsigned thread_id; 
unsigned ret; 

char s[80]; 


/* allocate stack for the new thread; stack size = 
4000bytes */ 

/* 80286 stack grows down but function malloc() returns a 
pointer to the bottom of the stack */ 

/* So to establish the correct pointer to the top of stack 
you need to add the returned stack pointer with the 
size of the stack */ 
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if ((new_stack = malloc(STACK_SIZE)) == 0) { 
printf(“\nmalloc(): not successful”) : 
DOSEXITCI,1)3 


few_stack += STACK SIZE: i* put the pointer to the 
top of stack */ 


/* start another. thread */ 
if (ret = DOSCREATETHREAD (thread2, (unsigned far *) 
&thread_id,new_stack)) { 
orintt (“\nDosCreateThread failed: %d",ret) : 
DOSEXIT (1,2) 3 
} 
strepy(s,”"This is primary’ thread”); 
VIOWRTCHARSTR(s,strlen(s),8,20,0); /* display character 
om etresn */ 


DOSSLEEP(5000L); /* the primary thread will sleep for 5 
seconds */ 
DOSEXIT (1,0); 
} 


/* thread #2 will print a message and exit */ 


void far thread? {) 


{ 
char s[80]; 


stropy(s, "This ia thread #2") ; 

/* display character on sereen */ 
VIOWRTCHARSTR(s,strlen(s),8,20,0); 
DOSEXIT(0,0); 
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Synchronization Between Threads 


It is sometimes necessary to control the execution of a thread. The two most 
basic functions OS/2 provides for this purpose are DosSuspendThread and 
DosResumeThread. These functions are used by a thread to suspend or resume 
the execution of another thread within the same process. To use these functions, 
the calling thread has to know the thread ID number of the thread which is to be 
suspended or resumed. The suspended thread only continues its execution after 
DosResumeThread is called. A thread cannot use the DosSuspendThread func- 
tion to control its own execution—it must use DosSleep. The two functions are 
primitive and therefore are not very useful. Other API functions provide a more 
elegant method for controlling the execution of threads (refer to Chapter 3 fora 
detailed explanation of inter-thread communications). 


DosSuspendThread (Thread_!D) 


DosResumeThread (Thread_ID) 


unsigned Thread_ID /* thread ID of the thread to be 
suspended or resumed */ 





DosSileep (Timelnterval) 


unsigned TimelInterval; /* length of time to sleep */ 





If Timelntervalis set to 0, the current thread is automatically preempted by the 
OS/2 scheduler, and must wait until OS/2 switches it back to the running state. 

After the thread sleeps for the specified time, it is put in the ready state. It must 
still wait, however, until OS/2 dispatches it. Therefore, the thread may sleep 
longer than the time specified by Timelnterval. 
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Example 


/* 


SUSPEND.C 


This example will demonstrate: 


* ff 


how to suspend and resume a thread using 
DosSuspendThread and DosResumeThread 


4#tinclude “malloc.h” 
#Hinclude “stdio.h” 
fHinclude “doscalls.h” 
Finclude “subcalls.h” 


+#define STACK SIZE 1024 


void far thread? (): 


main(argc,argv) 
Ink argc; 
char “*arevl[]; 


{ 


/* DOSCREATETHREAD arguments */ 


char far *new_stack; 
unsigned thread_id; 
unsigned ret; 

ehar s [80] : 


if ((new_stack = malloc(STACK SIZE)) == 0) { 
orintt(*\nmalioc(): mot successful”) ; 
DOSEXIT(t1.2); 


new steck “= STACK SIZE: /* put the pointer to top 
of stack */ 


/* start another thread */ 
if (ret = DOSCREATETHREAD (thread2, (unsigned far *) 
&thread_id,new_stack) ) 
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prints“ \loseGréateThread tailed: Yu", rer): 
DOSERTT(1 2) + | 
DOSSLEEP(1000L) ; /* the primary thread will sleep 
for 1 second */ 


DOSSUSPENDTHREAD (thread_id) ; 
DOSSLEEP(1000L) ; /* the primary thread will sleep 
for 1 gecond */ 


DOSRESUMETHREAD (thread_id); 
DOSSLEEP(1000L) ; /* the primary thread will sleep 
for 1 second */ 
DOSEXIT(1,0); 
} 


wold far thread? () 
{ 
char s[80];: 


orintt(*\n Secondary thread running”) ; 
while (1) { 
mipenar(*,.* )% 
} 
DOSEAIT (0,0) : 


Changing Process and Thread Priority 


At any given time, the OS/2 scheduler maintains one running thread, a list of 
ready threads, and a list of waiting threads. When the running thread is preempted 
after a certain time interval (a time slice), or waiting for an I/O operation, the OS/ 
2 dispatcher will switch a ready thread to the running state. OS/2 uses two criteria 
to determine which ready thread is to be switched to the running state: the pronty 
class and the prionty level of a thread. 

There are three priority classes, and within each class there are thirty-two 
distinct priority levels (0 to 31). The highest priority class threads are always 
dispatched first. Within each priority class, higher level threads run before lower 
level ones. Threads with the same priority class and priority level are scheduled in 
a FIFO (first-in-first-out) queue, which means that the first thread to come in to the 
queue is the first thread to be dispatched. 
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Figure 2.5 OS/2 Scheduler with Priority Class and Level. 





The highest priority threads belong to the time-critical class. ‘Time-critical 
threads will be serviced before any threads of a lower priority class. Next are the 
regular threads. ‘The majority of threads running under OS/2 are regular class 
which are serviced by OS/2 after all time-critical threads have been dispatched. 
Idle-time threads have the lowest priority class. Idle-time threads execute only when 
there are no regular or time-critical threads in the queue. 

When the OS/2 dispatcher wants to switch a thread to the running state, it 
compares the priority class of all the ready threads. The highest level time-critical 
thread is the first to be run. When there are no more time-critical threads, OS/2 
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dispatches the regular threads. Again, the higher priority level regular threads are 
executed first. When there are no time-critical threads and regular threads, 
OS/2 dispatches the idle-time threads. 

If there are many time-critical threads, then the regular threads will have to wait 
avery long time. To ensure that regular threads receive control of the CPU within 
a maximum-wait-time interval, OS/2 boosts the priority of a thread when it has not 
been executed after the maximum-wait-time. This method is called priority boosting. 

Two parameters in the “config.sys” file controlled the time slice interval and 
priority boosting interval, maxwait and tumeslice. The two parameters are specified 
in “config.sys” as follows: 


timeslice = maximum [,minimum] 
maxwait = seconds 


The timeslice parameter represents the maximum and minimum number of 
milliseconds OS/2 allows a thread to use the CPU for its execution before 
preempting the thread to allow the execution of another. The parameter maxwait 
specifies the maximum wait time interval that a thread waits without being 
executed. OS/2 automatically boosts the priority of a thread that has waited longer 
than maxwait seconds. 

After a thread completes an I/O operation it generally has a lot of data to 
process. The current version of OS/2 improves response time (and user satisfac- 
tion) by boosting the priority of a thread five levels after it completes an I/O 
operation. This insures that this thread executes before other regular threads. To 
disable priority boosting, the user can specify the parameter priority = absolute in 
the config.sys file. 


Priority API Functions 


There are two functions to query and set the priority of a process or thread, 
DosSetPrty and DosGetPrty. 


DosSetPrty (Scope, PriorityClass, PriorityDelta, ID) 


unsigned Scope; /* specifies thread or process priority 
change */ 

unsigned PriorityClas; /* priority class assignment */ 

unsigned PriorityDelta; /* change in priority level */ 


unsigned ID; /* target ID of process or thread */ 
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DosGetPrtty(Scope, Priority, ID) 


unsigned Scope; /* type of priority query */ 


unsigned far *Priority; /* pointer to location where priority is 
returned */ 


unsigned ID; /* ID of target process or thread */ 
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An “Invalid thread ID” error code is returned if the primary thread of the 
indicated process has been terminated. 


Example 


y* BREy.G 
This example will demonstrate: 


how to set and obtain threads’ priority via DosSetPrty and 
DosGetPrty 


“y 


#include “malloc.h” 
finclude “stdio.h” 
#include “doscalls.h” 
fHinclude “subcalls.h” 


4Kdefine STACK _SIZE 1024 
void far thread?2(): 


main(argc,argv) 
Int: Bree: 
char “arey ||]. 
{ 
/* DOSCREATETHREAD arguments */ 


char far *néw_ stack: 
unsigned thread_id; 


unsigned ret; 
char ¢ [80] ; 


/* Briority parameter */ 
unsigned Priority; 
if ((new_stack = malloc(STACK_SIZE)) == 0) { 


printt(*\amallec(): not successful”): 
DOSEZIT (CL, 1): 
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new _stack += STACK SIZE; /* put the pointer té the top sof 
stack */ 


/* Start another thread */ 

if (ret = DOSCREATETHREAD (thread2, 
(unsigned far *) &thread_id, 
new_stack) ) 


oriantt(“\obesCreateThread failed: Ya", fet) ; 
DOSERIT (1,2): 


DOSGETPRTY (2, j* 2 = thread 0 = process */ 
(unsiened far *)Priority, 
thread_id) ; 
printi(*\nThread ID: “d and Its Original Priority 
* thread _id,Prigrity) : 


DOSSETPRTY (2, /* 2 = thread © = process */ 
+10, 
thread id): 


DOSGETPRTY (2, /* 2 - thread 0 - procesa */ 
(unsigned far *)Priority, 
thread id); 
orints (*\alThread ID: Yd and Ite Current Priority 
“, thread _id,Pricrity): 


DOSEXIT(1,0) : 


voLd Far thread? {) 
{ 
char s [80]: 


printf(“\n Secondary thread running”) ; 
while (1) { 

} 

DOSEXIT (0,0); 
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Using Threads and Processes Efficiently 


Unlike MS-DOS programs, OS/2 applications are automatically well-behaved. 
An OS/2 program cannot address memory beyond the limits of its own LDT and 
therefore cannot corrupt other programs’ data and code. As long as OS/2 API 
functions are used, the program will happily coexist with other programs in the 
multitasking environment. OS/2 applications, however, have to be well-inten- 
tioned as well. A well-intentioned program should not be purposely destructive to 
the operating environment. For example, a program can be written to stop all 
running processes or to change the priority of other processes to idle-time class. 
To kill a process or change a process’ priority, only its PID is required. The PID, 
however, is only an integer variable. Any random integer can be the PID ofa 
running process. OS/2 assumes that an application is well-intentioned and does 
not have a protection mechanism against such a destructive program. 

To prevent the inadvertent corruption of other processes, an application 
cannot assume any default PID or thread ID. The PID and thread ID is incremen- 
tally assigned by OS/2 based on the number of executing processes and threads. 
Only values for PIDs and thread IDs returned by OS/2 can be used when calling 
process and thread functions. 

It is important to remember that the typical OS/2 user will run multiple 
sessions, or screen groups, and switch among them. Even if your application does 
not incorporate multiple threads or processes, OS/2 will be multitasking between 
your application’s primary thread and the primary threads of others programs the 
user is running. Because it is difficult to predict just what combination of 
applications will be running at any given time, a single program should not try to 
monopolize system resources. Users will generally be happiest if applications are 
designed to value the whole system performance over that of an individual 
program. Of course since this assumption covers only the “general case” it is up 
to the application designer to strike the right balance between system and program 
performance given the particular situation. 

In general, processes and threads should not be used over linear coding simply 
because their use provides an elegant structure. Use processes only to implement 
functions that use different resources and can be run independently as well as 
concurrently. Use threads for implementing functions that require the same 
resources but can be run concurrently. Threads should be used to access different 
devices with different I/O rates. 

Setting up a process with DosExecPgm requires a great deal of overhead (CPU 
cycles) from OS/2: creating the LDT, TSS, setting up memory for data, code, and 
stack segments, and then the program’s code and data must be read from the disk. 
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The programmer should avoid creating (using DosExecPgm) or destroying (using 
DosKillProcess) processes very often during the execution of an application 
because of the overhead required by these functions. For the sake of efficiency, 
when you must use processes, try to create all processes at the start of the 
application and then use the API interprocess communication functions de- 
scribed in the next chapter to send data between them. 

Processes should be used over threads when you want to protect functions’ 
resources from being accessed by another process. The use of processes facilitates 
memory protection because each process owns its own LDT. Sharing data and 
resources between processes can be accomplished using the interprocess API 
functions which are the topic of the next chapter. 

Functions should also be implemented as processes when they need to be 
externally identifiable, that is if they are to be shared by a number of applications. 
For example, a spell-checking function could be shared among a number of text 
preparation programs. If you need to develop applications that must use the same 
function differently under changing circumstances, you may wish to design them 
as a group of interchangeable and cooperating processes. A function that does not 
need separate resources and memory protection, and does not need to be 
externally identifiable, should be implemented as a thread. 


Chapter 3 


Inter-Process and Inter-Thread 
Communications 


rocesses were designed to run independently, and their resources are highly 
isolated from one another, making communication between them crucial 
to the success of a complex application. Threads were designed to work 
together to accomplish a task through interthread communication. In Chapter 2, 
we explained in detail how to create processes and threads and the basic functions 
for controlling their execution. With DosCWait, one process can wait for the 
termination of another process. With DosSuspendThread and DosResumeThread, 
one thread can control the execution of another. However, these functions are too 
primitive for more complicated forms of interprocess or interthread communica- 
tion. The major uses of interprocess and interthread communication are: sending 
signals between processes; synchronizing the execution of processes and threads; 
sharing serial reusable resources (SRRs); and transfering data among processes. 
The most primitive form of interprocess communication (IPC) is signaling. 
Signals are used to inform processes about crucial events which they cannot detect 
on their own (i.e., connection to the mainframe has just been broken, a worksta- 
tion has just logged off the network, or a hardware problem has developed). A 
process receiving a signal can then adjust its execution in response to an external 
event. Signals are implemented in OS/2 applications using flags and semaphores. 
In a multitasking system some devices and resources cannot be accessed by 
more than one thread at the same time. These are Serial Reusable Resources. Facilities 
have to be provided to insure that only one thread controls the SRR at any one time. 
This is called the provision of mutual exclusion for an SRR. OS/2 offers such 
facilities using critical sections and semaphores. Critical sections are used to provide 
mutual exclusion for threads within the same process. Semaphores are used both 
on an intraprocess or interprocess level. 
A step in complexity beyond interprocess or interthread signalling is synchro- 
nization between processes and threads. Synchronization means the execution of | 
a thread depends on a condition (or a set of conditions) in another, or a number 
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of other, processes or threads. This situation can become quite complex, with the 
execution of each thread working on a task dependent on the state of another or 
a number of other threads. On a simple level, a process or a thread must often wait 
for another process or thread to complete its task before it can get on with its own. 
For example, a program that analyzes a file from another computer can be divided 
into two threads: one that transfers the file, and one that analyzes it. The thread 
that performs the analysis must wait until the other thread signals completion of 
the file transfer before it can get on with its analysis. 

The most complex form of interprocess communication is the transfer of data 
between processes. (Threads automatically share all data owned by their parent 
process.) OS/2 provides three mechanisms for interprocess data transfer: shared 
memory, the pipe, and the queue. These methods vary in complexity, and are 
appropriate to different situations. The pzpeis the easiest to use. The pipe allows 
multiple processes to write to a single receiving process. The receiving process 
removes data from the head of the pipe, while the sending processes place data at 
the tail of the pipe (this data is in the form of a FIFO (first-in-first-out) bit stream). 
OS/2 takes care of all the synchronization and memory management needed to 
allow multiple processes to write to a pipe. 

A queueis like a pipe in that several processes can send data to a single receiving 
process; however, the queue is a more sophisticated method of data transfer. Data 
is sent on a queue in discrete elements; with the pipe it is sent asa data stream. This 
gives the receiving process the ability to read data at any point of the queue instead 
of just at the head (the case with the pipe). 

The queue’s greater power makes it more difficult to implement. The processes 
involved in using the queue must handle certain memory management functions 
themselves. The issues involved in using the the queue are so complex that we 
cover them in a separate chapter— Chapter 5. Refer to it for details. 

The most complex data tranfer resource is the shared memory segment. 
Numerous processes can both read and write to a shared memory segment. 
However, using a shared memory segment for interprocess data tranfer is compli- 
cated. Shared memory involves the use of memory functions as well as signaling 
and synchronization; it is covered in Chapter 4 with the rest of the memory 
functions. 

The following summarizes the features covered in this chapter: 


=" For signaling OS/2 provides flags and semaphores. 


=" The synchronization of processes and threads involves additional API 
functions that use flags and semaphores. 
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= Mutual exclusion among different processes and among threads in the 
same process is provided by semaphore functions. Mutual Exclusion 
among threads in the same process is provided by critical sections and 
semaphore functions. 


= The simplest interprocess data transfer mechanism is the pipe. It is used 
to tranfer data between one or more sending processes and a single 
receiving process in the form of a FIFO bit stream. (More complex 
mechanisms for data transfer are discussed in Chapters 4 and 5.) 


Using Flags for Signaling 


A flag is a variable with two possible values or states: on (1) or off (0); or multiple 
states: 0, 1,2, 3, etc. Achange in the state of a flag can represent a message between 
the sender and receiver. This is like the relationship between the pitcher and 
catcher in baseball: a pitcher sends predefined signs to the catcher to inform him 
of the pitch he’s about to throw. A thread can also send predefined flags to another 
thread in order to pass on important information. 

OS/2 provides three flags—A, B, and C—for signaling between processes. 
These flags, however, have no values that can be manipulated: they are used only 
for notification, to indicate “something has happened.” Two OS/2 API functions 
are used to manipulate the flags: DosSetSigHandler and DosFlagProcess. The 
sending process issues DosFlagProcess to signal the receiving process that “some- 
thing has happened.” This signal is received by the target process asa flag event. In 
order to receive the signal the receiving process must have previously used 
DosSetSigHandler to set up a handling routine. 

Using signals for IPC under OS/2 is analogous to using the old church bell that 
told the peasants the time. If you did not hear the bell when it was rung then you 
missed the signal, and perhaps a village feast. Similiarly, once a flag event is sent 
to the receiving process, if the receiving process did not set up a signal handler to 
process the event, the process misses it. The receiving process must already expect 
a flag event in order to receive one. 

There is no need for a separate facility to handle flags among threads, because 
all threads within a process share the same data. Flags, then, can be easily 
implemented using global variables. One thread can change the variable and 
another thread can monitor the variable and react according to the changes. 


90 Advanced Programmer's Guide to OS/2 


DosSetSigHandler 


DosSetSigHandler is the function that allows a process to handle external 
events. There are two types of external events to which a process can react. The 
first type are interrupts. These are generated when the the user enters Cntrl-C 
(SIGINTR) or Cntrl-Break (SIGBREAK) from the keyboard, or when the operat- 
ing system signals a process of its impending termination with SIGTERM. The 
second type of external event is called a flag event. (OS/2 provides three flags A, 
B, and C for interprocess signaling.) This section addresses only the subject of 
handling flag events. Chapter 7 discusses the use of DosSetSigHandler for the 
purpose of interrupt handling. 

A process has four choices for handling external events. It can allow OS/2 to 
take the default action associated with each type of event. It can replace the default 
OS/2 signal handling routine for a specific signal with one ofits own. It can choose 
to ignore a specific signal. Finally a process can choose not to act on a flag event, 
but at the same time inform the process that generated the flag event of its refusal. 
This last option, which amounts to a polite refusal on the part of the receiving 
process, allows for additional flexibility in the “conversation” between sender and 
receiver when using flags. 

If a process does not use DosSetSigHandler to set up handling routines for a 
specific signal, OS/2 automatically handles the signals with a default signal 
handling routine. For signals like SIGINTR, SIGBREAK, and SIGTERM, OS/2 
passes control to the command processor, CMD.EXE. The command processor 
issues the function DoskKillProcess to terminate the process which received the 
signal. The default action for the three flag events, A, B, or C is simply to ignore 
the signal. 3 

To handle a particular signal rather than take the default action, the process 
must: 

# Issue DosSetSigHandler with a specification as to the kind of signal the 
process will handle: SIGINTR, SIGBREAK, SIGTERM, Flag A, Flag B, or 
Flag C, and the type of action to take when the signal is received. If the 
process wishes to supply its own signal handling routine it must pass the 
address of the new signal handling routine in the DosSetSigHandler call’. 


= If the process institutes its own signal handler, DosSetSigHandler will 
return a previous handler address and previous action address. ‘Vhe previous 
handler address specifies the address of the old handling routine which was 


'If the process wants to set up signal handling routines for multiple signals it must make multiple calls of 
DosSetSigHandler. Each call should specify the address of a signal handling routine and the signal which it is 
to handle. 
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replaced by the new handling routine. The previous action address 
contains the value which represents the type of action that the previous 
handler would have taken for the specified signal. 


# A process that is handling flag events can call DosSetSigHandler with the 
option of refusing to accept a flag event. In this case the flagging process 
will receive an error code informing it that the flagged process refused to 
accept its signal. 


#" When the signal is received, OS/2 preempts the primary thread of the 
process to execute the new signal handling routine. The signal handling 
routine should immediately issue DosSetSigHandler to acknowledge that 
the signal has been received. This resets the signal handler and allows the 
process to handle another occurrence of the signal. 


#" When the current process no longer needs to handle the signal, it must use 
DosSetSigHandler with the previous handler address and previous action 
address to restore the previous signal handler. The restoration of the 
previous signal handler is crucial to insure the integrity of the system. 


When control is passed to the signal handling routine, two arguments are also 
passed to the handling routine. The first argument specifies the type of signal that 
was sent (interrupt or flag). If the signal is a flag event, the second argument will 
be the flag argument sent by the process which issued DosFlagProcess. If the signal 
is not a flag event, the second argument will be null. In order to receive the 
arguments, the signal handling routine must be declared in the following manner: 


void PASCAL far SigHandler(Sig Arg, Sig Number) 
unsigned Sig Arg; /* gienal ereuments */ 
unsigned Sig Number; /* signal number */ 


If the signal handling routine has been invoked and has immediately issued 
DosSetSigHandler in the acknowledgement mode, then the error handling 
routine will trap a second occurrence of the signal. However, ifa third occurrence 
of the signal takes place while the first handling routine is still executing, 
DosSetSigHandler will not be able to handle the third flag event. OS/2 sends error 
number 162 “Signal Pending” to the process that issued DosFlagProcess. Since 
OS/2 can only handle two flag events at a time (the one presently being handled 
and one more), signal handling routines should be quick and failsafe to assure that 
all possible signals are handled. 

When the signal handling thread is invoked by DosSetSigHandler it becomes 
the new primary thread for the process. If the the signal handling routine does not 
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execute within a single time-slice then it will be preempted by OS/2 and another 
thread will be dispatched. 

For assembly language signal handlers, when control is passed to the signal 
handling routine, the following arguments are passed on the stack: 


(SS:SP) The far return address. 
(SS:SP+4) Signal number of the signal received. 


(SS:SP+8) Signal arguments passed to the process by the 
flagger, the process which issued the DosFlagProcess. 


You may have noticed that the arguments in the above assembly call are in 
reverse order from the arguments in the earlier Cdeclaration. SigArgcomes before 
SigNum, which is not the case for the parameters passed to the stack. This is because 
the Pascal method of argument passing is used for signal handlers. In the Pascal 
method of argument passing, the last value pushed onto the stack must be declared 
as the first parameter on the function line. 

When the signal handling routine is invoked the CS, IP, SS, SP, and flag registers 
are loaded with new values to represent the code and stack of the signal handling 
routine. All other registers retain the same values they had when the signal was 
received. The signal handling routine should terminate with a FAR, or interseg- 
ment return which allows OS/2 to resume execution of the interrupted thread. 
There is no need for the signal handling routine to save and restore the contents 
of the registers as with DOS 3.x interrupt handlers. After the execution of the 
signal handling routine OS/2 restores the registers to their original state. The 
signal handling routine can change the stack frame in order to transfer control to 
another routine, butin this case OS/2 can’t restore the the contents of the registers 
to their original values. It is up to the signal handling routine to do so. 


DosSetSigHandler (RoutineAddress, PrevAddress, PrevAction, Action, SigNumber) 


void pascal (far *) RoutineAddress; /* pointer to new handling routine */ 


unsigned long far *PrevAddress; /* pointer to old handling routine */ 
unsigned far *PrevAction; /* previous action code */ 
unsigned Action; /* new action code */ 


unsigned SigNumber; /* signal being handled */ 
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Compatability Mode Restriction 


In the compatibility box, a real mode process does not have a primary thread 
to handle signals. Therefore, the only event the signal can handle is SIGINTR. In 
real mode, the value Action has only three possible values (0 to 2). Any other values 
generate the error “Invalid Signal Number.” The only values possible for SigNum- 
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ber are SIGINTR and SIGTERM. Any other values for SigNumber also generate the 
error “Invalid Signal Number.” 


DosFlagProcess 


DosFlagProcess is used in conjunction with DosSetSigHandler to implement 
interprocess signalling. It is used by a process to transmit the occurrence of a flag 
event to another process. 

Itis misleading to speak of a flag event in the terms of setting or clearing the flag. 
Flags A, B, and C do not have any static value which can be examined after the fact. 
DosFlagProcess does not set a flag but rather notifies the target process that a flag 
event is occurring. If the receiving process ignores the signal, it cannot later 
examine the value of the flag to see whether or not the flag has been set. Once the 
flag event is ignored, the receiving process has already missed the event. The only 
value associated with the flag is flag argument. 

If the flagged process does not react to the flag event it may be useful for the 
flagging process to examine the error code returned by DosFlagProcess. Using the 
error code, the flagging process can, to some extent, determine the state of the 
receiving process and react accordingly. There are only two possible errors: the 
receiving process refused the signal (error 156) or the “Signal already pending” 
message (error 162) which means that another signal is currently being handled 
by the receiving process. The former error is returned if the target process has 
chosen to politely refuse all flag events. This latter error is returned if the receiving 
process is concurrently handling two signals. (Refer to the previous section for 
more details.) 


DosFlagProcess (PID, Action, FlagNum, FlagArg) 


unsigned PID; /* the receiving process ID */ 

unsigned Action; /* indicate type of receiving process */ 

unsigned FlagNum; /* specifies the number of flag to be 
Bet 


unsigned FlagArg; /* argument of the flag event */ 
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Compatability Mode Restrictions 


DosFlagProcess is not a family API function and is not available in real mode. 
DosSetSigHandler is available in real mode but only with limited functions: to 
handle Cntrl-C or Cntrl-Break signals. 


Examples 


* 


* signal.c 


* 
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* This program demonstrates how to capture flag signals using 
DosSetSigHandler and DosFlagProcess. 


This program spawns another process, “SIGNAL2.EXE”, which sets 
up the signal handler. This program then uses DosFlagProcess to 
send signals to SIGNAL2.EXE. 


Note: the return code of DosFlagProcess should be examined 
carefully. If the error code is 162, “signal pending”, the 
sending process should retransmit the signal again. This error 
indicates that the receiving process is still in the middle of 
processing the previous signal. 


This program sends 5 flag A signals and one flag C signal to 
inform the child process to terminate. 


ae 


include <doscalls.h> 
include <subcalls.h> 
include <stdio.h> 


#fdefine SIGFLAGA 0 /* Flee nunbars */ 

ftdefine SIGFLAGB 1 

ft}define SIGFLAGC 2 

#tdefine ERR_SIGPENDING 162 /* SIGNAL is pending */ 

char PgmName[] = “SIGNAL2.EXE”; 

void main({) { 
/* deta for DeskxeePan */ 

struct ResultCodes ReturnCodes:/* return code structure */ 

j/* there is no 


environment buffer */ 


unsigned i; 
unsigned PID; 


unsigned ret; 
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printf(“\nSpawn SIGNAL2.EXE”) ; 
ret = DosExecPgm ((char far *)0, 


O, 

1; /* Asynchronous Execution */ 
(char far *)0, J/* eareument */ 

(char far *) 0, /* pull envptr */ 
&ReturnCodes, 


(char far *)PgmName) ; 


printf(*\nSleep for 1 second,..”); 

DosSleep((long) 1000); /* sleep for 3 seconds 
allowing child process 
to catch up */ 


a. eS 
while (i < 5) { 
printf(“\nSending Signal: FlagA”); 
ret = DosFlagProcess(ReturnCodes.TermCode_PID, 


f* pia 7 
ie /* only parent process will be notified*/ 
SIGFLAGA, 
i 
/* if signal is pending send again */ 
if lrecy { 
if (ret == ERR_SIGPENDING) { 
DosSleep((long)500);/* wait a few tic */ 
continue; 


printf(“\nFlagA Process failed, error code 


yd” ,ret); 
a 
/* send termination signal */ 
Printt(*\nsendinge Flag C: quit signal”): 
ret = DosFlagProcess(ReturnCodes.TermCode_PID, ae ts ae 
Tia /* only parent process will be notified*/ 


SIGFLAGC, 
ie 
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DosCWait (1, /* wait until child process end */ 
a; 
(struct ResultCodes far *)&ReturnCodes, 
(unsigned far *)&PID, 
ReturnCodes.TermCode_PID) ; 


DOSERTE (1, 03% 


* 


* signal2.c 


* 


* This program demonstrates how to capture flag signals using 
DosSetSigHandler. 


Signal2.exe will simply invoke DosSetSigHandler, then sleep ina 
loop while waiting for signals from the SIGNAL.EXE process. It 
is recommended that thread 0 should not do any kind of process- 
ing in order to guarantee that all signals will be captured. 


In this program, the primary thread simply waits in a sleep 
loop. We will use the flag argument of FLAG C as a means for 
the parent process to inform SIGNAL2.EXE to quit. 


Note: The signal handler must “acknowledge” that a signal has 
been trapped in order to receive the next signal. 


You can have one signal handler to handle multiple type of 
signals and flags, or to have a separate handler for each sig- 
nal. 


ve 


+#include <doscalls.h> 
include <subcalls.h> 
#Finclude <stdio.h> 


#fdefine SIGINTR i /* possible signals */ 
#fdefine SIGTERM 3 
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ftdefine SIGBREAK 
Htdefine SIGFLAGA 
ttdefine SIGFLAGB 
ttdefine SIGFLAGC 


—~J OV Wa oe 


ttdefine SIG DEFAULT 
4Edefine SIG_IGNORE 


0 /* parameters for Action parameter */ 

1 
#fdefine SIG_CATCH 2 

3 

4 


4tdefine SIG ERR 
tedefine SIG ACK 


/* need to prototype the sig handler routine to satisfy the 
compiler */ 


void pascal far Asig_handler(); 
void pascal far Csig_handler(); 


unsigned Quit; /* global flag 


void main() { 


void (pascal far *Aprev_address) (); 
unsigned Aprev_action; 

void (pascal far *Cprev_address) (); 
unsigned Gprev_action: 

unsigned ret; 


/* pap sienal */ 
ret= DOSSETSIGHANDLER(Asig_ handler, /* signal handler 
address */ 
(unsigned long far *) &Aprev_address, 
(unsigned far *) &Aprev_action, 
SIG CATCH, /* eecept sisnal */ 
SIGFLAGA) ; /* trap flag A 
signal */ 


if (ret) { 
printf (“\n DosSetSigHandler for Flag A failed. Error 
eode %d.”, ret); 
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DOSEAIT (1,023 


ret= DOSSETSIGHANDLER(Csig handler, /* signal handler address */ 
(unsigned long far *) &Cprev_address, 
(unsigned far *) &Cprev_action, 


STG. CATCH, /* accept signal */ 
SIGFLAGC) ; /* trap fleas © signal */ 
if (ety f 
printf (*\n DosSetSigHandler for Flag C failed. Error 
code %d.”, ret); 


BOSERIT (LG): 


GQicit = 0; /* af the argument for flag C is 1 */ 
/* the signal handler will set the */ 
f= Quit fleas */ 

while (!Quit) /* leop until the flag feceived */ 

DOSSLEEP( (long) 10000) ; /* sleep for 10 seconds */ 


/* Restore previous signal handler. 

there is no need to restore the flag signals. 

We’ve included it here because it is the correct protocol 
io take in sisnal handline.*/ 


ret= DOSSETSIGHANDLER (Aprev_address,/* signal handler address */ 
(unsigned long far *) O, 
(unsigned far *) 0, 
Aprev_action, 
SIGFLAGA) ; 


if (ret) { 
printf(“\n Cannot restore Flag A. Error code %d”, 
ret); 


BOSERAIT( 2,0} + 
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ret= DOSSETSIGHANDLER(Cprev_address,/* signal handler address */ 
(unsigned long far *) 0, 
(unsigned far *) O, 
Cprev_action, 
SIGFLAGC) ; 


if (ret) { 
Erigtel~ in Cannot restore Flag C. Error code %d.,”, 
ret); 
DOSEXIT(1,0); 


DOSEXTT (1,0) 


void pascal far Asig_handler(sig_arg, sig num) 
unsigned sig arg, sig num; 
{ 


int ret: 
prinet ("no Receiving Flag A, are: “%d”,sie_are) ; 


/* we did not want to acknowledge the flag before the 
printf statement to insure that another signal will 
not be received while printing. */ 


/* acknowledge that the signal is received */ 
ret = DOSSETSIGHANDLER ((void (far *)()) OL, 
(unsigned long far *) O, 
(unsigned far *)0O, 
SIG_ACK, 
sig num) ; 


if (ret) 
printf(“*\n Acknowledge Flag %d failed. Error code: %d”, 


sig num, ret); 


void pascal far Csig_handler(sig_arg, sig num) 
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unsigned sig _ arg, sig num; 


{ 


int ret; 
pranrt(* VA Receiving Flas C”); 
if (¢i0 aro == 1) 

Quit = 1; 


/* we did not want to acknowledge the flag before the 
printf statement to insure that another signal will 
not be received while printing. */ 


/* acknowledge that the signal is received */ 
ret = DOSSETSIGHANDLER ((void (far *)()) OL, 
(unsigned long far *) 0, 
(unsigned far *)0, 
SIG_ACK, 
sig num); 


if (ret) 
prinie(” \n Acknowledge Flag %d failed. Error code: %d”, 
sig num. fet): 


Using Critical Sections for Mutual Exclusion 


In a multitasking system, there are shared devices and data structures which 
should only be accessed by one thread ata time. Certain devices may be physically 
damaged by allowing multiple processes to access them simultaneously. Equally 
important, data might be corrupted if two or more processes try to modify it at the 
same time. Such devices and data are the serial reusable resources (SRR). For 
example, if two threads try to simultaneously paint the video display without being 
aware of the other thread’s intention, one thread’s display might overlap the 
others, or the display might be a wild combination of both. In either case, the user 
will not understand the information displayed. 

Whenever serially reusable devices are shared between processes and threads, 
mechanisms and policies are needed to protect them. Mutual exclusion must be 
established—mutual exclusion means allowing only one thread at a time to have 
access to an SRR. The need to protect physical devices that can only handle one 
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process at a time is self-evident, but the need to protect data from being accessed 
concurrently is clearer with an example. 

We’ll look at an application with several processes. It needs to keep track of the 
number of records in a file by updating the variable Yotal_record when there is a 
change in the number of records. 

Consider what happens when two processes attempt to increment the variable 
Total_record. Suppose the current value stored in the database of TYotal_record is 
2000. Process 1 and process 2 both read the same value of 2000 for Total_record . 
Process 1 increments Total_record to 2001 and saves it on the database. Process 2, 
now in control of the CPU, also increments Total_record to 2001 and saves the 
variable to the database. Because of the uncontrolled access by multiple processes 
to the same variable, the value of the variable is now incorrect. 

A similar problem exists with the manipulation of 32-bit global variables by 
multiple threads within C programs. The C compiler uses several 80286 instruc- 
tions to perform 32-bit calculations, especially multiplication and division. The 
OS/2 scheduler, however, may preempt the running thread after the completion 
of a single 80286 instruction. Therefore, when performing 32-bit calculation, it is 
possible that the running thread will be preempted before it has finished a 
calculation. If another thread tries to use this variable, which is currently in a 
undertermined state, it will receive an incorrect value for the variable. 

In order to implement the concept of mutual exclusion, when process | reads 
Total_record from the file to increment the variable, it must prevent any other 
process from doing so. OS/2 will be the policeman that enforces this rule by 
halting the execution of the other processes wanting to access the same variable 
until process | has written the new value of the variable to the database. ‘Then one 
of the waiting processes is allowed to continue its execution. This ensures that 
when process 2 reads the variable Yotal_record from the database, it reads the 
correct value. 

The problems of protecting an SRR described above are common in multi- 
tasking systems, and occur not only when several processes or threads must access 
the same memory variables, but also when you wish to provide common access to 
other devices: files, printer, keyboard, serial port or any SRR. OS/2 automatically 
handles mutual exclusion for devices like the graphics adapter, disk controller, 
keyboard, mouse, and asynchronous port. But there are other SRRs which are not 
automatically protected by OS/2 like global data structures. For these, OS/2 offers 
mechanisms which allow the programmer to set up mutual exclusion. These 
mechanisms are called Critical Sections and Semaphores. Critical sections are used to 
implement mutual exclusion among threads. Semaphores, however, can be used 
by both threads or processes. (The concepts of critical section and semaphore 
were introduced by Dijkstra, one of the founding fathers of computer program- 
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ming, in his work Cooperating Sequential Processes *.) 


Critical Sections 


A critical section is the section of code within a thread whose execution cannot 
be preempted by any other threads in the same process. During the execution of 
one thread’s critical section, OS/2 will not allow other threads of the same process 
to run. 

To demonstrate the use of critical section in establishing mutual exclusion, we 
will reuse the problem of protecting the variable Total_record. 


Suppose the following is 
the pseudo-code used to 
modify the variable 
Total_record: 


Without the usage of criti- 
cal section, the pseudo- 
code used to modify 
Total_record for thread 1 
would be: 


The same pseudo-code is 
used by thread 2 to modify 


Total_record: 


Procedure modify_TOTAL_ RECORD 

Begin 
read database for TOTAL RECORD 
TOTAL RECORD = TOTAL; RECORD + 1 
write TOTAL RECORD to database 

End 


Procedure Thread_l 
Begin 

CALL modify_TOTAL_RECORD 
End 


Procedure Thread 2 
Begin 
CALL modify_TOTAL_RECORD 


Begin 


* Dijkstra, E.W., Cooperating Sequential Processes, Technological University, Eindhoven, The Netherlands, 1965. 
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The three procedures above lead to unrestricted and uncontrolled access to the 
variable Yotal_record, because both threads | and 2 are able to call the procedure 
modity_Votal_record at the same time. Using critical section, both threads can tell 
OS/2 that they are not to be preempted by any other thread in the same process 
while they are modifying Yotal_record. ‘They thus establish controlled access to the 
data structure. 


The implementation of Procedure Thread_1 
critical section using Begin 
pseudo-code for threads 1 


miler Critical Section 
and 2 would be: 


CALL modify_TOTAL_RECORD 
EXit Critical Sectien 
End 


Procedure Thread 7 


Begin 
Enter. Critical Seetion 
CALL modify_TOTAL_RECORD 
ESit Gri titel. section 
End 


The pseudo-function Enter_Critical_Section notifies the operating system that 
the code that follows must be executed without preemption from any other 
threads of the same process. The function Exit_Critical_Section informs OS/2 
that the execution of the critical section is completed, and the operating system 
can let other threads run. 

When thread | runs, it executes Enter_Critical Section, and thread 2 is 
prevented from executing. The procedure modify_VTotal_record completes its 
modification of the database without preemption. During this procedure, the 
integrity of the variable Yotal_record is guaranteed, because it cannot be changed 
by another thread until the correct value is saved to the database. When thread 2 
reads Total_record from the database, it will get a correct value. If both thread 1 and 
thread 2 try to execute at the same time, OS/2 allows only one Enter_Critical_Section 
call to be effective, preventing either thread | or thread 2 from executing. When 
the first thread completes its use of the critical section (by issuing the 
Exit_Critical_ Section call) the other thread is allowed to run. The two OS/2 API 
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functions that implement the Enter_Critical_Section and Exit_Critical_ Section 
psuedo-functions are named DosEnterCritSec and DosExitCritSec, respectively. 

Critical section can be used only within the same process and affect only the 
execution of threads owned by that process. Ifa thread issues DosEnterCritSec, no 
other threads owned by the process will run, but threads owned by different 
processes will not be affected. Using critical sections, a process can implement 
mutual exclusions to share SRRs among its threads. To implement mutual 
exclusions between processes, system semaphores are needed. They’re covered in 
the next section. 

Because other threads within the process can’t run while a thread is in a critical 
section, the program code for a critical section should be simple and quick. Ifa 
thread hangs during the execution of a critical section, other threads are also 
unable to resume their execution, so the programmer must use them carefully. 

Critical section should not be implemented within the primary thread espe- 
cially when there are signal handlers. Because OS/2 uses the primary thread for 
signal handling, if the primary thread is in a critical section and a signal occurs, 
~ execution of the critical section is halted to handle the signal. If another thread 
accesses the SRR this may place the SRR in an undeterminate state. Ifa secondary 
thread is within a critical section and a signal occurs, OS/2 preempts the critical 
section to handle the signal, but other threads are not allowed to run. Signal 
handlers, therefore, should not use resources protected by a critical section. 


DosEnterCritSec and DosExitCritSec 


DosEnterCritSec and DosExitCritSec are simple functions which indicate the 
start and the end of a critical section, respectively. Every time a DosEnterCritSec 
is used in a section of code, there must be a corresponding DosExitCritSec. No 
arguments are needed for these two functions. 

They must be used together. An error will occur if DosExitCritSec is used 
without a previous call to DosEnterCritSec. If a critical section is entered with 
DosEnterCritSec and DosExitCritSec is never called, then no other threads 
belonging to the same process will be able to execute. While in a critical section, 
the running thread can only be preempted if a signal occurs. 


DosEnterCritSec () /* Signifies the beginning of a critical 
section */ 


DosExitCritSec() /* Signifies the end of a critical section */ 
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Compatability Mode Restriction 


The functions are not available. 
Example 


/* 
CRITSEC.GC 


This program demonstrates how to use DosEnterCritSec and DosEx- 
itCritsSec. 


This program mirrors the pseudo-code described in this section. 


We will use critical sections to protect and SRR, the global 
variable Total_Record. Thread 1 will assign the value 1 to the 
variable. Thread 2 will only assign the value 2 to the vari- 
able. 


= 


include “malloc.h” 
fHinclude <doscalls.h> 
include <stdio.h> 
#Hinclude <dos.h> 


d+edefine STACK SIZE 4000 


unsigned Total_Record; /* this is the SRR we need to protect */ 
unsigned complete= 0; /* thread complete flag */ 

/* af thread 2 complete, thie flag is set */ 
void far thread2(); 
void Modify_Total_Record() ; 


main(argc,argv) 

int argc; 

char *arev|[|; 

{ 

/* DOSCREATETHREAD arguments */ 
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char far *new_stack; 
unsigned thread_id; 
unsigned return_code; 
unsigned i; 


/* allocate etack for the new thread, stack size = 4000bytes */ 

/* 80286 stack grows down but function malloc() returns a 
pointer to the bottom of the stack */ 

/* So to establish the correct pointer te the top of etack */ 

/* you need to add the returned stack pointer with the size of 
the stack */ 


4£ ((new_stack = (char far *) malloc (STACK SIZE)) == 0) { 
printf(“\nStack allocation for new thread, malloc(), not 
successful”) ; 
DOSHZIT(L,1)3 


new_stack t= STACK _SIZ2ZE; /* mit the pointer ta the top of 
stack */ 


/* etart another thread */ 

Priict (“\nereatine Thread 2”): 

if (return_code = DOSCREATETHREAD (thread2, 
(unsigned far *) &thread_id, 
new_stack)) 


printf (*\ndosOreateThread failed: Gu”*,return_code) : 
DOSEXIT (1,2): 


for {i = O21.“ 5S? ae) J 
Modify_Total_Record( 1 ); 
DOSSLEEP ( (long) 20) ; /* sleep a few ticks allowing */ 
/* the other thread to catch up */ 
} 
while (!complete); 


DOSEXIT(1,0); 
} 
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/* thread #2 will call Modify_Total_Record then waits a few tick 
before it’s done, it will set the complete flag */ 


void far thread? ()} 
{ 


thc + 


bor £2. =] 0s 2“. 55 22) 4 
Modify_Total_Record( 2 ); 
DOSSLEEP ( (long) 20) ; /* sleep a few ticke allow 
ing for the other thread 
to eateh wp */ 


complete = 1; 


DOSEXIT(O,0) ; 


void Modify_Total_Record (value) 
unsigned value; 
{ 
DOSENTERCRITSEC() ; 
printfi("\ninside Critical Section”): 
Total Record = valtie; 
printt(*\nValue change to: %d”,Total Record) : 
DOSEXITCRITSEC();: 


Semaphores 


Semaphores are the most versatile interprocess communication tool OS/2 
provides. They can be used for signaling, synchronization, and the establishment 
of mutual exclusion. Semaphores, however, are not available for real mode 
(compatability box) applications. Before using semaphores for these purposes we 
need to define a semaphore and the basic operations for semaphore manipula- 
tion. A semaphore can be viewed as a variable with two distinct states, setand clear. 
Putting a semaphore in either set or clear state is referred to as settingor clearing the 
semaphore. 

The instructions to set and clear semaphores cannot be prempted by the 
scheduler, or the semaphore may be left in an undetermined state. This is 
especially important because the execution of other processes depends on the 
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state ofa semaphore. To insure that a semaphore exists only in a set or clear state, 
the setting and clearing of semaphores are atomic OS/2 instructions. An atomic 
instruction is one that cannot be prempted by the scheduler. 80286 assembly 
instructions are also atomic instructions. They are different from the operations 
used for 32-bit mathematical calculations, which can be preempted during 
calculation, leaving the variable in an underterminate state. By establishing the 
setting and clearing of semaphores as atomic operations, OS/2 allows only two 
states for a semaphore: set or clear. 

There are two kinds of Semaphores: RAM semaphores and system semaphores. A 
RAM semaphore is a long variable (double word or 32 bits) declared within the 
application. The handle of a RAM semaphore is the address of the variable. Since 
all threads share the same data, RAM semaphores are best used for interthread 
communication. When a RAM semaphore is declared, it should be initialized to 
zero signifying that it is in the clear state. RAM semaphores can be used for 
interprocess communication only if the cooperating processes have shared access 
to the memory area where the RAM semaphore variables are declared. This 
method, however, requires using shared memory API functions. Because of the 
complexity involved in using shared memory, RAM semaphores are recom- 
mended to be used among threads of the same process. When different processes 
need to communicate through a semaphore, system semaphores are recom- 
mended. 


RAM Semaphores System Semaphores 

Recommended for Recommended for interprocess 
interthread communication. communication. 

Long (32-bit) variable. Must be created using DosCreatSem or 


opened via DosOpenSem. 


Handle is the address of the Handle returned by either DosCreateSem 
long variable. or DosOpenSem. 

Can be used for IPC, if the Can be used for interthread 

variable is stored ona communication. 


shared memory segment. 


No limits. Limits to 128 semaphores for the 
entire system. 


Table 3.1 Differences between RAM semaphores and system semaphores. 
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System semaphores are a special OS/2 system resource. In order to use a system 
semaphore for IPC, one process must first create the semaphore. The other 
processes can then obtain access to it. As part of its maintenance procedures, 
OS/2 releases the semaphore after the termination of a process. When a process 
abruptly terminates, OS/2 sends an error condition to any other processes using 
the semaphore. 

System semaphore is defined as a pseudo file with a file name of the form: 


\SEM\semaphore_name. 


No file or directory “\SEM” actually exists on the disk drive; semaphores are kept 
in a special memory location protected by OS/2. 

Each semaphore is specified by a semaphore handle. ARAM semaphore handle 
is only an address of the variable. Since system semaphores are resources 
maintained by OS/2, the handle of the system semaphore is a special index that 
has to be translated into a memory location. This memory location is protected 
and can be directly accessed only by OS/2. 

Because the operating system manipulation of system semaphores involves a 
complex protocol, more CPU cycles are required than that for RAM semaphores. 
This extra work, however, allows system semaphores to be used by different 
processes. System semaphores should be implemented for interprocess commu- 
nication and RAM semaphores should be used for interthread communication. 

System semaphores are system resources. The ceiling on simultaneously active 
system semaphores is: 128. It is recommended, however, that no application use 
more than 6 system semaphores at a time, since in a multitasking system it is 
difficult to know how many other applications are running. 


Semaphore Functions 


There are three groups of semaphore functions. One group is specifically for 
creating and closing semaphores. Another is used to manipulate the state of the 
semaphore. The last uses semaphore functions for the synchronization of process 
and thread execution by allowing a thread to wait until a semaphore is clear. 
Combined, these semaphore functions provide the most versatile means of 
interprocess communication. 


Create, Open, and Close Semaphore 


System semaphores have to be created using API function DosCreateSem 
before being used. One process has to create the semaphore using DosCreateSem. 
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After creating the semaphore, other processes wanting to use it must issue 
DosOpenSem to open the semaphore. The semaphore name used by the creating 
process, and the name specified by the other processes for opening have to match 
exactly. The semaphore names can be determined in advance for all the processes 
involved or passed to the sending processes via arguments through DosExecPgm, 
or by shared memory, or by pipe. After creating or opening the semaphore, 
OS/2 returns a semaphore handle to the calling process. The handle is necessary 
when calling other semaphore functions. 

RAM semaphores do not have to be created. A long variable merely has to be 
declared by the application. The handle of the RAM semaphore is its address. 

Once it no longer needs a system semaphore a process uses DosCloseSem to 
release it. The application itself should release all system semaphores. OS/2 
automatically releases system semaphores after the termination of a process, but 
sends an error condition to all other processes using them. 


Setting and Clearing Semaphores 


We discussed functions used to create, open, and close semaphores. Another 
group of semaphore functions is provided by OS/2 for changing the semaphore 
state. Because a semaphore can have only two possible states, set and clear, the state 
changing functions are very simple. Function DosSemSet puts the semaphore in 
the set state. Function DosSemClear puts the semaphore in the clear state. Both 
of these functions are applicable to either RAM or system semaphores. 

Setting and clearing a semaphore are the simplest operations that can be 
performed on a semaphore using these functions for mutual exclusion, signalling 
or synchronization, are explained in later sections of this chapter. In this section, 
we cover only the syntax of the two functions. 


Semaphore Waiting Functions 


The next group of semaphore functions allows a process to synchronize its 
actions with those of other processes by allowing a process to control its own 
execution in response to a semphore state. These functions are: DosSemWait, 
DosSemSetWait, DosSsemRequest and DosMuxSemWait. They can be used with 
both RAM and system semaphores. These functions work similarly for both 
threads and processes. Combining these synchronization functions with state 
manipulation semaphore functions, a process can implement signaling, mutual 
exclusion and interprocess synchronization. We will discuss how to combine these 
semaphore functions in later sections of this chapter. 
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Level Triggered and Edge Triggered Semaphore Functions 


There are two types of semaphore waiting functions: level triggered and edge 
triggered. They differ in the way a change of semaphore state affects the execution 
of any thread waiting for thatsemaphore. Edge triggered semaphore functions are 
good for interprocess signaling, while level triggered semaphore functions lend 
themselves to the provision of mutual exclusion for SRRs. There are three level 
triggered semaphore functions supported by OS/2: DosSemWait, DosSetSem- 
Wait, and DosSemRequest. There is only one edge triggered function: DosMuxSem- 
Wait. 

A level triggered semaphore function can be formulated directly in terms of the 
mutual exclusion problem. The semaphore acts as a token that is passed around 
among a set of threads wishing to use the same SRR. Whichever thread currently 
possesses the token (whichever thread has set the semaphore) has exclusive 
control over the SRR. The execution of all other threads that try to access the SRR 
is halted until the semaphore is cleared. When the thread currently in possession 
of the SRR is finished, it leaves the token (clears the semaphore) for the next 
thread that wants to use the SRR. Notice that under this scheme only one thread 
at a time can set the semaphore, thus the mutual exclusion needed to protect an 
SRR is achieved. But in order to explain exactly how a level triggered function is 
implemented by OS/2 we refer again to the concept of thread dispatching. 

Recall that a thread may be in any one of three states: running, ready, or waiting. 
When a thread’s execution is halted to wait for a level triggered semaphore event, 
it is placed in. the ready state (not in the waiting state as you might expect, and as 
would be the case with an edge triggered function). Consequently each thread 
waiting for a semaphore to be cleared with a level triggered semaphore function 
continues to be periodically dispatched by the scheduler. When such a thread is 
dispatched, one of two things happens. The thread either finds the semaphore 
cleared and begins executing (it must then take possession of the SRR by imme- 
diately setting the semaphore). Or this thread finds that the semaphore is still in 
the possession of another process (it finds it set) and the same instruction that 
checks the status of the semaphore halts its execution. The halted thread is then 
placed at the rear of the dispatch queue of ready threads to be executed again in 
the future. Because level triggered functions involve the scheduler, there is no way 
to predict which waiting thread will execute first, if all have the same privilege level 
(see Chapter 2). 

Notice that using level triggered semaphore functions, many threads compete 
for control of the same semaphore which can associated with any SRR. If the first 
thread to find the semaphore clear immediately sets it again, none of the other 
waiting threads are informed of the change in the semaphore’s state. It is also 
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possible to use level triggered functions so that a single change in the state of a 
semaphore is signaled to manu waiting threads. Having the thread which has 
found the semaphore clear, not reset, accomplishes this. As each waiting thread is 
dispatched it receives news of the semaphore event. 

The programmer must be very careful using level triggered functions to allow 
multiple threads or processes to wait for a single semaphore event. If a thread 
should change the state of the semaphore before all the waiting threads have been 
dispatched, these undispatched threads will not be appraised of the change of state 
in the semaphore that time around. 

Edge triggered semaphore functions, on the other hand, are best suited for 
signaling. They are also easily explained: any threads waiting for a semaphore with 
an edge triggered function resume their execution as soon as the semaphore is 
cleared, even if itis immediately set by another thread. This is because any threads 
waiting with an edge triggered function are placed in the waiting state, and once 
the semaphore clears they are switched as a group into the ready state. Thus a 


Set of Running 


my 


Threads 


Set of Running 
Threads 


Set of Blocked 
Threads 


Figure 3.1. (a) A group of Threads (in grey) waiting ona 
semaphore with an edge triggered function (b) 
When the semaphore clears all waiting threads 
begin running 





Figure 3.1 Level triggered semaphores 
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process or thread can signal many processes or threads that an event has occurred 
and they can all be triggered to execute. There is also an advantage in error 
handling when an edge triggered function is used because all waiting threads are 
sent error messages deriving from the use of the semaphore. When using level 
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(a) Thread A has set the semaphore and is now the currently executing thread. 
The other thread s waiting on the semaphore continue to be periodically 
dispatched by OS/2, but upon finding the semaphore set , they are returned 

to the rear of the dispatch queue 

(b) Thread A has cleared the semaphore 

(c) The semaphore is set by Thread C, which becomes the currently executing 
thread 





Figure 3.2 Edge Triggered Semaphores 
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triggered functions, only the first successfully dispatched thread receives any error 
messages. The only edge triggered semaphore function supported by the current 
version of OS/2 is DosMuxSem Wait. 

Both edge triggered and level triggered semaphores are useful for various 
synchronization problems. Be cautious when using level triggered functions to 
establish communication among several processes or threads for the reasons 
described earlier. 


DosCreateSem 


DosCreateSem creates a system semaphore for the calling process. Other 
processes must use DosOpenSem to establish access to this system semaphore. 
Once created or accessed, the semaphore can be manipulated using other 
semaphore functions. 

The creating processes may place constraints on how other processes access a 
system semaphore by declaring it exclusive or nonexclusive. If the process which 
issues DosCreateSem chooses the exclusive ownership option, then only the 
creating process has the ability to change the state of the semaphore. This means 
that only threads belonging to the process that created the semaphore are allowed 
to use functions changing the semaphore’s state. Threads belonging to any other 
processes are allowed only to monitor the state of the system semaphore and react 
to these changes. A nonexclusive option allows any process to change the state of 
the semaphore and facilitates two-way interprocess signalling. Therefore, a non- 
exclusive system semaphore must be created for the purpose of mutual exclusion. 

DosCreateSem returns the handle of the created semaphore. This handle is 
required for any future references to that semaphore, either by the semaphore 
waiting functions or by the functions that alter the state of the semaphore. 
DosCreateSem both creates and opens the semaphore for the calling process. The 
creating process does not need to use DosOpenSem. Before terminating, the 
creating process should use DosCloseSem to free up the system resources taken up 
by the semaphore. 

If a child process is spawned by the creating process, any open semaphore 
handles are inherited by the child process. The child process should be careful 
using the semaphore handles inherited by the parent process. If the semaphore 
created with the exclusive option, the child process cannot alter its state. There is 
no function available allowing a child process to determine the resources which it 
has inherited. The child process either must know beforehand which semaphore 
or file handles to use or the parent process must explicitly supply this information 
to the child process. 
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DosCreateSem (Sem_Option, Sem_Handle, Sem_Name) 


unsigned Sem_Option; /* semaphore ownership option. OS/2 
Tech Reference refers to this variable 
as Nokxclusive */ 


unsigned long far *Sem_Handle /* address to store the Semaphore 
handle */ 
char far *Sem_Name; /* pointer to an ASCIIZ string containing 


the semaphore name */ 





Inter-Process and Inter-Thread Communication 119 





DosOpenSem 


DosOpenSem allows a process access to a system semaphore that was created by 
another process (using DosCreateSem). A semaphore can be opened if it was 
created by another process, and if it remains opened by at least one process 
including the one that created it. Ifa semaphore is closed by the last process using 
it, OS/2 discards it. A discarded semaphore cannot be opened by another process 
unless the semaphore was created using DosCreateSem. 

Once a process has access to a semaphore, any thread within that process can 
perform semaphore functions. If the exclusive ownership option is not set, then 
the process can manipulate the state of the semaphore (setting it or clearing it). 
In addition to opening the semaphore, DosOpenSem returns its handle. This 
handle is used to identify the semaphore when using other semaphore functions. 
The use of DosOpenSem does not change the state of the semaphore. 

Once a semaphore is opened, any child process spawned by the process also 
inherits the semaphore handle. The child process has the same access rights to the 
semaphore as its parent. 


DosOpenSem (Sem_Handle, Sem_Name) 


unsigned long far *Sem_Handle /* address to store the Semaphore 
handle */ 
char *Sem_Name; /* pointer to an ASCIIZ string containing 


the semaphore name */ 
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DosCloseSem 


DosCloseSem is used to close an open system semaphore when the process no 
longer needs it. A process should close all opened semaphores before it terminates 
execution. Routines should be set up to do this using DosExitList in the case of 
abnormal termination. OS/2 automatically closes all opened semaphores belong- 
ing to a terminated process, though it does not clear them. 

Before closing a semaphore, a process should clear if it owns the semaphore. 
Clearing the semaphore allows any other processes currently waiting on the 
semaphore to continue their execution. 

If the closing process is the only remaining process accessing the semaphore, 
OS/2 erases the semaphores from the system. The semaphore cannot be opened 
by another process after that; it must be recreated to be used again. 


DosCloseSem(Sem_Handle) 


unsigned long Sem_Handle; /* semaphore handle to be closed */ 
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DosSemSet and DosSemClear 


DosSemSet and DosSemClear are used to set or clear both system semaphores 
and RAM semaphores. Once the semaphore is set by a thread, the semaphore is 
considered to be owned by the thread. When the semaphore is cleared, it is 
considered to be wnowned. 

The semaphore handle is required by DosSemSet and DosSemClear. System 
semaphore handles are returned by DosCreateSem or DosOpenSem. The handle 
of a RAM semaphore is the address of the double word (long) variable containing 
the semaphore. RAM semaphores should be initialized to zero so that the RAM 
semaphore is in the clear state. 

If a system semaphore is created with exclusive ownership option, Sem_Option 
= 0, the semaphore cannot be set or clear by any process other than the process that 
created it. In order to use the semaphore for mutual exclusion it must be created 
with the nonexclusive ownership option, Sem_Opition = 1, to allow other processes 
to alter the state of the semaphore. 

DosSemSet puts the semaphore in the set state and DosSemClear puts the 
semaphore in the clear state, regardless of the present state of the semaphore. 
DosSemSet and DosSemClear are both atomic operations which means that 
OS/2 cannot preempt a thread that is calling either of these functions, and thus 
leave the semaphore in an undetermined state. By making semaphore setting and 
clearing atomic operations, OS/2 ensures that the semaphore exists in either the 
set or clear state at all times. This is crucial since most semaphore operations 
involve one or more threads waiting for a change in the semaphore’s state. If the 
semaphore is in the set state, the thread waits. Once the semaphore is cleared, any 
thread that is currently waiting for it wakes up and continues executing. A 
semaphore cannot be in an undeterminate state because this would render the 
operations of semaphore functions useless. 


DosSemSet (SemHandle) 


unsigned long SemHandle; /* semaphore handle */ 


DosSemClear (SemHandle) 


unsigned long SemHandle; /*semaphore handle */ 
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Using Semaphores for Mutual Exclusion 


We already covered implementing mutual exclusion between threads in the 
same process using critical sections. Level triggered semaphores can also be used 
to implement mutual exclusion. In the previous section we explained the basic 
functions for managing semaphores: how they are created, accessed, and released 
or destroyed. We also discussed the functions for the most basic semaphore opera- 
tions, setting and clearing a semaphore. To use the semaphore for mutual exclu- 
sion we need another operation called Wazt until Semaphore is clear. This operation 
causes a thread to suspend its execution until a semaphore is in the clear state. 
Once the semaphore is cleared the waiting thread resumes its execution. In order 
to protect an SRR the waiting operation must be level-triggered (see pages 20 
through 30). 

To demonstrate how these three semaphore operations are used to establish 
mutual exclusion, let’s look again at the problem with the variable Total_record as 
discussed earlier. The problem involves two asynchronous threads. Each thread 
can modify the variable Total_record which is stored on a database. Total_record is 
used to keep track of the number of records currently on the database. The value 
of Total_record is corrupted if both threads try to change the variable at the same 
time. In order to prevent the corruption of this variable some form of mutual 
exclusion must be provided. 

Using the three semaphore operations described earlier, the pseudocode for 
establishing mutual exclusion would be as follows: 


If the main procedure of Procedure modify_TOTAL_RECORD 
the program remains the Begin 
same: 


read database for 

TOTAL RECORD 

TOTAL RECORD = YOTAL RECORD - 1 

write TOTAL RECORD to database 
End 
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If we assume that the initial Procedure Thread_l 

state of the semaphore is clear, Begin 

the pseudo-code for thread WAIT until SEMAPHORE is clear 
1 and 2 using the semaphore 


SET SEMAPHORE 
CALL modify_TOTAL_RECORD 
CLEAR SEMAPHORE 


would be: 


End 


Using DosSemRequest for Mutual Exclusion 


To implement the mutual exclusion described above, use the API functions 
DosSemRequest and DosSemClear. DosSemRequest is a combination of the two 
semaphore operations described above: Wait until semaphore is clear and Set the 
semaphore. DosSemClear merely clears a semaphore. 

The function DosSemRequest is a level triggered waiting function that imme- 
diately resets the semaphore upon gaining control of it. This means that when the 
semaphore has been cleared, only one other waiting thread is dispatched by the 
operating system. OS/2 combines the waiting and setting operations in one 
atomic function to ensure the integrity of the semaphore. Ifa thread had to issue 
separate instructions to wait on and set a semaphore the scheduler will preempt 
this thread after the waiting operation, allowing it to resume execution, but leaving 
the semaphore in the clear state. ‘The semaphore value incorrectly allows another 
waiting thread to be dispatched, even though the first thread is also running and 
had intended to establish exclusive control of the SRR. By combining the two 
operations into one function, the semaphore is automatically be set as soon as a 
waiting thread has been dispatched. This assures ownership of the semaphore 
associated with an SRR by a single thread. 


DosSemRequest 


The function DosSemRequest allows a thread to wait on the clearing of a 
semaphore and to take possession of it (by setting it and executing) when it finds 
it clear. This level-triggered semaphore function assures that only one thread at 
a time can take possession of the SRR associated with a semaphore. 

There are three wait options for DosSemRequest. The thread can wait 
indefinitely until the semaphore is clear; wait only a specified number of seconds 
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for the clearing of the semaphore; or not wait at all. These three options give a 
thread flexibility in the way it accesses an SRR. The second option allows a thread 
to terminate its waiting, if it has not yet gained control of the SRR, after a certain 
amount of time. The last option lets a thread poll the SRR to see if any other thread 
has control. Both these options free a thread to do other things while an SRR is 
in use. 

DosSemRequest requires a semaphore handle which is returned by 
DosCreateSem or DosOpenSem. The handle of a RAM semaphore is the address 
of the double word (long) variable containing the semaphore. If the system 
semaphore was created with the exclusive ownership option, Sem_Opiion = 0, it 
cannot be set or cleared by any process other than the one that created it. If the 
semaphore is to be used for mutual exclusion it must be created with the 
nonexclusive ownership option, Sem_Option = 1, to allow other processes to alter 
the state of the semaphore. 

If the process which currently owns the semaphore terminates without closing 
it OS/2 returns error number 105, “Owner ended owning semaphore,” to the 
waiting thread. This could mean the process has terminated abnormally. How- 
ever, not every thread waiting for the semaphore gets the error. Since DosSemRe- 
quest is a level triggered function, only the thread next in line for control of the 
semaphore once it is cleared, receives the error. 

Once the thread receives this error, it should try to set the semaphore. If 
OS/2 allows the semaphore to be set without an error, it can continue to be used 
for mutual exclusion. If further errors occur, the thread which receives this error 
must release the semaphore and abort the mutual exclusion operation by notifying 
the other processes involved. Programmers should always consider the possibility 
of abrupt termination of other threads when writing multiprocess application and 
recover accordingly using function DosExitList (see Chapter 2) asa way of cleaning 
up semaphore resources. 


DosSemRequest (Sem_Handle, Time_Out) 


unsigned long Sem_Handle; /* semaphore handle */ 


long Time_Out; /* time-out option */ 
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Semaphores vs. Critical Section 


Critical section can only be used to establish mutual exclusion among threads 
of the same process. When multiple processes are involved, the only method 
available for the implementation of mutual exclusion is the system semaphore. 

Using critical sections for mutual exclusion among threads within the same 
process assures the protection of an SRR on the intraprocess level. This is because 
no other threads within the same process will be dispatched. Critical sections are 
easy to implement, but they have the drawback of stopping the execution of all 
other threads in the process, even threads that have nothing to do with the 
protection of the SRR in question. If there are many different SRRs to be protected 
within a process, or if the threads that implement the critical sections take up a lot 
of CPU time, the performance of the process is very unsatisfactory. 
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Using semaphores controls the scope of the mutual exclusion. Only threads 
actually involved in accessing the SRR have to halt their execution while the SRR 
is possessed by another thread. The problem with using semaphores for mutual 
exclusion is that all the threads accessing the SRR must cooperate with one 
another, by agreeing to issue a semaphore waiting function. It's up to the 
programmer to pian for this when coding the application. It will be interesting to 
see whether a protocol will be developed so that independent applications can 
work together to share share SRRs for which OS/2 does not provide mutual 
exclusion. 

Both semaphores and critical sections can be used to implement mutual 
exclusion for SRRs on the intraprocess level. We recommend semaphores over 
critical sections because with them the range of exclusion can be specifically 
defined. Also, threads do not monopolize processor resources when using sema- 
phores; they can be preempted to allow other more important threads to execute 
(such as those ata higher privilege level or those doing I/O). Froma systems point 
of view, semaphores are better than critical sections because the whole process may 
hang if a thread hangs during the execution of a critical section. Critical sections 
are, however, easier to program than semaphores. Use them when the process 
needs to protect only one SRR and the critical section is quick and doesn’t slow 
down the process too much. 


Using Semaphores for Synchronization 


OS/2 provides useful semaphore functions for synchronizing the execution of 
processes and threads. Using them it is possible to devise complex choreographies 
by which multiple processes, and multiple threads, cooperate to accomplish a task 
as efficiently as possible. In the previous section we explained how semaphore 
functions are used to implement mutual exclusion. Semaphore functions can be 
used in much the same way to implement more subtle forms of synchronization. 

Synchronizing the execution of several processes can be accomplished using 
signals. One process sends the signal to another. The receiving process halts its 
execution with a conditional loop, and starts its execution again once the signal 
changes. For example, when a mainframe data file has to be downloaded to the 
PC for analysis, the application can be designed with one process downloading the 
file and another process performing the analysis. The process receiving the trans- 
ferred file signals the process doing the analysis to wait in a loop. Once the file is 
transferred, the receiving process sends a different signal telling the waiting 
process to break out of the loop and perform the analysis. This method eats up 
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CPU cycles and demands extra coding from the programmer. To eliminate this 
extra overhead when implementing synchronization, OS/2 provides extensive 
functions for controlling the execution of processes and threads using sema- 
phores. 

Synchronization requires a combination of signaling and execution control. 
Four semaphore functions allow processes and threads to synchronize their 
execution in reaction to external events (to changes in the status of asemaphore). 
Three—DosSem Wait, DosSemSetWait, and DosSsemRequest—are level triggered, 
meaning that care should be taken when using them to set up synchronization 
among a number of processes or threads. The function DosMuxSemWait is, 
however, edge-triggered. It allows a process or thread to send a message to other 
processes or threads. DosMuxSemWait provides an added feature which allows a 
process or a thread to wait for a change in status of several semaphores. 


DosSemWait 


DosSemWait halts the execution of the current thread until the semaphore 
specified is in the clear state. If the semaphore is clear before the execution of 
DosSemWait, the thread’s execution is unaffected. There are several options for 
DosSemWait. The thread can wait indefinitely until the semaphore is clear; it can 
seta limit on the amount of time it waits; or it can not wait atall. The no wait option 
is used when a thread or a process merely wishes to test the state of the semaphore. 

Using DosSemWait, the pseudocode for the situation discussed above would be: 


Procedure RECEIVE 
Begin 
CREATE Semaphore with non-exclusive option 
(DosCreateSem) 
SET Semaphore (DosSemSet) 
download file 
CLEAR Semaphore (DosSemClear) 
End 
Procedure ANALYSIS 
Begin 
OPEN Semaphore (DosOpenSem) 
WAIT until the Semaphore is clear (DosSemWait) 
analyze file 
End 
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DosSemWait requires a semaphore handle. System semaphore handles are 
returned by DosCreateSem and DosOpenSem. The handle of a RAM semaphore 
is the address of the double word (long) variable containing the semaphore. RAM 
semaphores should be initialized to zero to indicate that the semaphore’s state is 
clear. 

OS/2 returns error number 105, “Owner ended owning semaphore,” to the 
waiting thread if the process which currently owns the semaphore terminates 
without closing it. This can mean the owner process has terminated abnormally. 
Not all threads waiting for the semaphore get the error. Since DosSemWait is a 
level triggered function, only the thread next in line for control of the semaphore 
(once the semaphore is cleared), receives the error. If this error is received, the 
semaphore may be in an undetermined state. (Ifa semaphore is in an undeter- 
mined state, the semaphore can be cleared. Once it is clear, OS/2 does not send 
error 105 to the next thread waiting for control of the semaphore.) 

Ifa thread receives this error, it should try to recover. If the process that owned 

the semaphore terminated abnormally, the receiving thread should take appropri- 
ate action. If more than one thread is involved in the synchronization, then that 
thread will have to notify these other processes (The use of DosMuxSemWait 
eliminates this problem). Programmers should always consider the possibility of 
abrupt termination of other threads in writing multiprocess applications; use 
function DosExitList (Chapter 2) to clean up semaphore resources. 
_ Once a thread receives this error, it should just try to set the semaphore. If 
OS/2 allows the semaphore to be set without any error, the thread can continually 
use the semaphore for mutual exclusion. Otherwise, the thread must release the 
semaphore and abort the operation by notifying other processes involved. 


DosSemWait (Sem_Handle, Time_QOut) 


unsigned long Sem_Handle; /* semaphore handle a 


unsigned long Time_Out; /* time-out option */ 





Inter-Process and Inter-Thread Communication 129 





DosSemSetWait 


DosSemSetWait sets a semaphore and waits for it until the semaphore is cleared 
by another process. DosSemSetWait acts as the inverse of DosSemWait. It is used 
when a process or thread is waiting for an event. The processes or threads which 
are to signal the event must clear the semaphore to allow the waiting process to 
continue execution. The problem proposed above can be solved using DosSem- 


SetWait this way: 


Procedure RECEIVE 

Begin 
OPEN Semaphore (DosOpenSem) 
download file 
CLEAR Semaphore (DosSemClear) 


End 
Procedure ANALYSIS 
Begin 
CREATE Semaphore with non-exclusive option 
(DosCreateSem) 
SET and WAIT until the Semaphore is clear 
(DosSemSetWait) 


analyze file 
End 
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DosSemSetWait has several options. The thread can wait indefinitely until the 
semaphore clears; wait for specified number of milliseconds until the semaphore 
clears; or not wait at all. The no wait option is used just to check the condition of 
the semaphore: whether it is set or clear. 

A semaphore handle is required by DosSemSetWait. The system semaphore 
handles are returned by DosCreateSem or DosOpenSem. (The handle of a RAM 
semaphore is the address of the double word [long] variable containing the 
semaphore. Remember, RAM semaphores should be initialized to zero to clear the 
semaphore.) 

If the system semaphore is created with the exclusive option, Sem_Option = 0, it 
cannot be set or cleared by any process except the process that created it. To allow 
other processes to alter the state of the semaphore it has to be created with non- 
exclusive option, Sem_Option = I. 

DosSemSetWait is a “level-triggered” semaphore function. To briefly recap, 
level tnggered means that if the semaphore is cleared and then set immediately by 
another thread, the current thread still has to wait. The waiting thread resumes 
its execution onlyif the semaphore is clear at the moment the scheduler dispatches 
the waiting thread. If the semaphore is not clear at that moment it will be placed 
in the ready state until the next timeslice when it once again tests the semaphore. 


DosSemSetWait (Sem_Handle, Time_Out) 


unsigned long Sem_Handle; /* semaphore handle */ 


unsigned long Time_Out; /* time-out option */ 
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Example—(System Semaphore) 


#fdefine WAIT -1L /* wait options */ 
4tdefine NOWAIT OL 

+#define NON EXCLUSIVE 1 /* owner options */ 
4Kdefine EXCLUSIVE 0 


char SemName[]=”\\SEM\\TESTSEM” ; 
unsigned long SemHandle; 


DosCreateSem (NON_EXCLUSIVE, (long far *)&SemHandle, 
(char far *)SemName) ; 


DosSemSetWait (SemHandle, WAIT): 


(Ram Semaphore) 
long SemHandle; 


DosSemSetWait((long )&SemHandle, WAIT); 
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DosSemRequest 


This function is used primarily to implement mutual exclusion. It is a level 
triggered semaphore function where the process waits until the semaphore is clear 
and then sets the semaphore. The calling process must clear the semaphore, 
allowing all other waiting processes to continue. 


DosMuxSemWait 


DosMuxSemWait allows a process to wait for multiple semaphores. When any 
one of the semaphores clears, the process continues its execution. This function 
also informs the process or thread of which semaphore has cleared. This is a useful 
function: it allows the process to synchronize its own execution according to the 
status of a series of events. The status of each event can be represented by the status 
of each semaphore. 

Because this function allows a thread to wait for anumber of semaphores its use 
is different than that of other semaphore functions. When one of the specified 
semaphores is clear, OS/2 returns an index representing its handle to the calling 
process. Using this handle, the calling process can determine which event in the 
series has occurred. 

The parameters required by DosMuxSemWait are different from the rest of the 
semaphore functions. A list of semaphore handles must be provide following a 
specific format. When any of these semaphores is clear, DosMuxSemWait returns 
an index number specifying which. Since DosMuxSemWait immediately returns 
an index when any semaphore on the list is cleared, the programmer cannot 
assume that the other semaphores are still set. If several semaphores are cleared 
at the same time, DosMuxSem Wait only returns the index of the number of the one 
which cleared first. If a thread cannot miss a semaphore event, it should not use 
DosMuxSemWait. There is no way to guarrantee that a thread waiting on multiple 
semaphore events will be able to catch every one. For crucial semaphore events a 
separate thread should be dedicated to each semaphore. 

Unlike other semaphore waiting functions, DosMuxSemWait is an edge trig- 
gered function; if any semaphores clear, OS/2 automatically allows all waiting 
threads to resume operation. It does not matter whether that semaphore is set 
again immediately by another process. Because of this feature, DosMuxSemWait 
is well suited for making sure that all processes or threads waiting on a semaphore 
event are notified of its occurrence. 

There are three waiting options for DosMuxSemWait. The thread can wait 
indefinitely until the semaphore is clear; wait for a specified number of millisec- 
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onds for the semaphore to cleared; or not wait at all. The no wait option is used 
to test for the set or clear condition of the semaphore. 

OS/2 returns error 105, “Owner ended owning semaphore,” to all waiting 
threads if the process which currently owns the semaphore terminates without 
closing it. This advantage can make the extra complexity involved in using the 
function worthwhile, such as when the execution of several processes depends on 
one semaphore event. 


DosMuxSemWait (IndexNum, ListAddr, TimeOut) 


unsigned far *IndexNum; /* index number specifying which 
semaphore has been cleared */ 
char far *ListAddr; /* list of addresses of all the 


semaphores */ 


long TimeOut; /* time out option */ 
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Example—DosMuxSemWait 


/* MUXSEM.C 
This program demonstrates how to use DosMuxSemWait. 


In this example, we will only wait for three semaphores 
consisting of two ram semaphores and one system semaphores. 


The following structures are defined for DosMuxSemWait. 


struct SEM { 
unsigned reserved; 
unsigned long Semaphore; 


r4 
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struct MUXSEM { 
unsigned SemCount; 


struct SEM SemListli]: wwhere 0 <i < 16 
} MuxSem; 
unsigned reserved; 
unsigned long Semaphore; ;represents the actual semaphore 


shandle to be tested 
DOSMUXSEMWAIT was designed for system semaphores. 
Using RAM semaphores with the function is a bit cumbersome. 


Because a RAM semaphore is the address of a DWORD variable. We 
need to assign the address of the variable to the member of the 


array. 
long ramsem; 
unsigned long array[16]; 
ramsem = OL; ; clear the Ram semaphore 
array[i] = (long )&ramsem; swhere 0 < i < 16 

“ 


f#Hinclude <stdio.h> 
#Finclude <doscalls.h> 
include <malloc.h> 
#Finclude <dos.h> 


#tdefine EXCLUSIVE 0 /* ereaate option */ 
HHdefine NONEXCLUSIVE 1 
HHdefine STACK SIZE 4000 


#fdefine WAIT -1L i” “gad eptionme */ 
#fdefine NOWAIT OL 
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struct SEM { 


unsigned reserved; 
unsigned long Semaphore; 
I 
struct MUXSEM { /* muxsemwait structure */ 


unsigned SemCount; 
struct SEM SemList [5]; 


} MuxSem; 


void far thread? (): 


long Complete= OL; /* thread complete semaphore */ 


/* 4 thread 2 complete, this 
semaphore is set */ 


char SemName[]=”\\SEM\\TEST”; 


main() 


unsigned IndexNum; 
long seml = OL; /* RAM semaphore */ 


unsigned ret, thread_id; 
char far *new_stack; 
/* first Semaphore will be a system semaphore */ 
ret = DOSCREATESEM(NONEXCLUSIVE, 
(long far *)&MuxSem.SemList[0].Semaphore, 
(char far *)SemName) ; 
if (ret) { 
printf(“\nDosCreateSem failed: %d”,ret); 
DOSES IT (1:0) 


/* notice how we have to assigned RAM semaphore */ 


MuxSem.SemCount = 3; 
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MuxSem.SemList[1].Semaphore = (long) &seml; 
MuxSem.SemList[2].Semaphore = (long) &Complete; 


17 ((new stack = (char far *) malloc (STACK SIZE)) = 0g) { 
printf(“\\nmalloc() failed”); 
DOSEXIT( 1,133 


new stack += STACK SIZE; /* put thea pointer to the top of 
stack */ 


DOSSEMSET (MuxSem.SemList[0].Semaphore); /* set all 
semaphores */ 

DOSSEMSET (MuxSem.SemList[1].Semaphore) ; 

DOSSEMSET (MuxSem.SemList[2].Semaphore) ; 


/* start another thread */ 

if (ret = DOSCREATETHREAD (thread2, 
(unsigned far *) &thread_id, 
new_stack) ) 


printt(“\\nbosCreateTharesad failed: “u",ret) ; 
DOSEXIT(1,2) 


while (iy 4 /* call DosMuxSemWait */ 
ret = DOSMUXSEMWAIT( (unsigned far *)&IndexNum, 
(unsigned far *)&MuxSem, 
WAIT) 3 
if (ret) { 
printf(“\nDosMuxSemWait failed: %d”,ret); 
DOSEXIT(1,0); 
/* display which semaphore was cleared */ 
printf(“\nSemaphore %d cleared.”,IndexNum) ; 


/* if semaphore was the complete flag, exit */ 
if (IindexNum == 2) { 

printf(“\nthread 2 completed. Exiting.”); 

break; 
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/* set the semaphore again */ 
DOSSEMSET (MuxSem.SemList [IndexNum] .Semaphore) ; 
DOSEXIT(1.0) 3 


Toid far Thread? () 
{ 


/* this procedure just keep clearing semaphores on the list */ 
$e 


DOSSLEEP ( (long) 1000) ; /* sleep for a second */ 
for (i =O; 4 % 34 a4) 
ter (7=0+ 5 “ 23 4) f 
printf(“\nThread 2 clear semaphore Index %d”,j); 
DOSSEMCLEAR (MuxSem.SemList[j].Semaphore) ; 
DOSSLEEP((long)100); /* sleep for a few tick */ 


DOSSEMCLEAR( (long) &Complete) ; 
DOSEALL LO. 0) 


This example demonstrates how to use API functions DosSem Wait, DosSemSet- 
Wait, DosSemSet, and DosSemClear for synchronization. 


Example—System Semaphore 


/* SEMNAME.H -Include file for SEMAPHOR.C and SEM2.C */ 
ffdefine WAIT -1L /* walt optiens */ 
#fdefine NOWAIT OL 

define EXCLUSIVE 0 {* epeate option */ 
itdefine NONEXCLUSIVE 1 

char SemName[] = “\\SEM\\TOTAL”; /* semaphore names */ 


char SemName?2 [| “\\SEM\\SYNC” ;_ 
char filename[] = “TOTAL.DAT”: 


| 
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/* 
SEMAPHOR.C 


This program demonstrates: 
: how to create system semaphores via DosCreateSem. 


how to use System Semaphore using DosSemRequest and Dos 
SemClear to protect an SRR between two processes. 


how to use System semaphore for synchronization between 
processes. 


We will use semaphores to protect an SRR, the Total_Record store 
in file TOTAL.DAT. 


ny 


fHinclude <doscalls.h> 
#Hinclude <stdio.h> 
include <dos.h> 
#include <fcentl.h> 
fHinclude <sys\types.h> 
include <sys\stat.h> 
fFHinclude <share.h> 
#tinclude <io.h> 


include “semname.h” 


char PgmName[]=”SEM2.EXE”; 
int. £d; 


void Modify_Total_Record(); 


main(argc,argv) 
Int arec; 
char *arev[]: 


{ 
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lone TotalSem, SyneSem: /* total and synchronization */ 
/* gemaphores */ 


struct ResultCodes ReturnCodes:/* return code structure */ 
/* there is no environment buffer */ 


unsigned ret; 
unsigned i; 


ret = DOSCREATESEM(NONEXCLUSIVE, /* ereates two 
semaphores */ 
(leng far *)&TotalSem, /* one for total 
record */ 
(char far *)SemName) ; 
ret = DOSCREATESEM(NONEXCLUSIVE, /* and for 
synchronization */ 
(long far *)&SyncSem, 
(char far *)SemName2) ; 
t£ fer 
printf (“\nSemaphor: DosCreateSem failed: %d",ret); 
DOSEAIT (1.0) 
} 
DOSSEMCLEAR (TotalSem) ; /* elear total semaphore */ 


DOSSEMSET (SyncSem);/* set the synchronization semaphore */ 
ret = DOSEXECPGM((char far *)NULL, /* ObjNameBuf */ 


(unsigned) 0, /* ObjNameLen */ 
(unsigned) 1, /* AsyneTraceFlags */ 
(enar far *) NULL; /* Argument Ptr */ 
(char far *) NULL, /* Bavironment. Pir */ 


/* ITD & Termination Codes */ 
(struct ResultCodes far *) G&ReturnCodes, 
(char far *) PgmName ); /* child program name */ 


if (ret) { 
printf(“Semaphore: DosExecPgm failed: %d\n”, ret); 
DOSEXIT(1, 0); 
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/* open file using sopen() - C run-time library */ 


fd = sopen(filename, O_CREAT | O_RDWR, SH_DENYNO, 
S_IREAD | S_IWRITE) ; 


if (fd == -1) { 
printf(“\nSemaphor: Sopen failed”); 


DOSEXIT (1.0)% 


DOSSEMWAIT(SyncSem, WAIT); /* wait till child process 
cleare */ 
DOSSEMSET (SyncSem) ; /* telling we that it*@e ready */ 


for (1 = GO: 4 < Se tes) f 
ret = DOSSEMREQUEST(TotalSem, WAIT): 


if (ret) { 
printf(“\nSemaphore: DosSemRequest failed: 
yd”, ret); 
break; 
} 
Modify_Total_Record(fd,1 ); 
DOSSEMCLEAR (TotalSem) ; 
DOSSLEEP ( (long) 20) ; 
} 
DOSSEMWAIT(SyncSem, WAIT); /* wait till child process 


completes */ 


DOSCLOSESEM(SyncSem) ; 
DOSCLOSESEM(TotalSem) ;: 


close (fd): 


DOSEXIT(1,,0) : 


void Modify_Total_Record(fd, value) 


int fd; 
unsigned value; 


Static int Total Rerord = 0: 
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lgeek (fd, 0L,0); /* position to the bof */ 


read (fd, &Total. Record, sizeof lint) ): 

Total Record?=value: 

printf(“\nSemamphore: Total_Record: %d”,Total_Record) ; 
lseek(f£d,0L,0); /* position <6 the bor *7 
write (fd,6Total Record ,e1zéo0f (int) ): 


SEM2.C 


This program demonstrates: 


Open System semaphores via DosOpenSem. 


how to use System Semaphore using DosSemRequest and Dos 
SemClear to protect an SRR between two processes. 


how to use System semaphore for synchronization between 
processes. 


We will use semaphores to protect an SRR, the Total_Record store 
in file TOTAL.DAT. 


oe 


include <doscalls.h> 
include <stdio.h> 
fFinclude <dos.h> 
Finelude <fentl.h> 
fHinclude <sys\types.h> 
#Hinclude <sys\stat.h> 
#Hinclude <share.h> 
fFHinclude <io.h> 


4include “semname.h” 


void Modify_Total_Record(); 
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Main(larec,arey) 
int argc; 
ohare “are ) + 


{ 


long TotalSem, SyncSem; /* total and synchronization */ 
/* semaphores */ 


struct ResultCodes ReturnCodes: /* veturn code 
structure */ 
/* there ig no environment buffer */ 
unsigned ret, i; 
int td: 
/* open two semaphores */ 


DOSOPENSEM( (lone far *)&TotalSem, i* ene for toral 
record */ 


ret 


(char far *)SemName) ; 


ret = DOSOPENSEM( (long far *)&SyncSem,/* and for 
synchronigation */ 
(char far *)SemName2) ; 


if (ret 
printf(“\nDosCreateSem failed: %d”,ret); 
DOS EAT sO): 


/* open file weine eopéen() - € run-time library */ 


fd = sopen(filename, O_CREAT | O_RDWR, SH_DENYNO, 
S_IREAD | S_IWRITE) ; 


a (id = =A) 
printf(“\nSem2: Sopen failed”) ; 
DOSEXIT(1,0); 


[44 Advanced Programmer's Guide to OS/2 


DOSSEMCLEAR (SyncSem) ; /* clear the synchronization 
semaphore */ 


fer ta = Oe 2 «ae att 4 
ret = DOSSEMREQUEST(TotalSem, WAIT); 
if (ret) { 
printf(“\nSem2 DosSemRequest failed: %d”,ret); 
break; 
} 
Modify Total Recerd(fid,1). 
DOSSEMCLEAR (TotalSem) ; 


DOSSLEEP((long) 20); 


DOSSEMCLEAR (SyncSem) ; /* wait till child proceas 
completes */ 


DOSCLOSESEM(SyncSem) ; 
DOSCLOSESEM(TotalSem) ; 
close (fd) ; 
DORE IT (1.0) 


void Modify_Total_Record(fd, value) 
nt. a: 
unsigned value; 


static ant Total Record = OG; 


lseek(fd,0L,0); /* position to the bor */ 


read(fd,&Total Record,sizeof(int)); 


Total Recotdt=value: 
orintt (*\nSem2: Tetal Record: %d”, Total Record) ; 
lseak (fd, 0L,0); /* see ttion to the bot */ 


write(fd,é&Total Record, sizeof{int)): 
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Example—RAM Semaphore 


/* 
RAMSEM.C 


This program demonstrates: 
- how to use RAM semaphores to protect an SRR using 
DosSemRequest and DosSemClear. 


2 Using Ram Semaphores for synchronization between two 
threads via DosSemSet, DosSemWait and DosSemClear. 


We will use semaphores to protect an SRR, the global variable 
Total_Record. Thread 1 will assign the value 1 to the 
variable. Thread 2 will only assign the value 2 to the 
variable. 


Also to prevent the primary thread from exiting before thread 2 


is completed, we have set-up another semaphore “Complete”. When 
thread 2 starts execution, it will set the semaphore, and only 
clears it until it completes its execution. The primary thread 


use DossemWailt, to wait till thread 2 is finished. 
ny 


#include “malloc.h” 
include <doscalls.h> 
include <stdio.h> 
4#Hinclude <dos.h> 


4Kdefine STACK. SIZE 4000 


#fdefine WAIT = 1 /* wait aprions */ 
#fdefine NOWAIT OL 


unsigned Total_Record; /* this is the SRR we need to protect */ 
long Complete= OL; /* thread complete flag */ 

/* if thread 2 complete, this flag is set */ 
long Semaphore = OL; 
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void far thread? (): 
yoid Modify Total, Record () ; 


main(argc,argv) 

Lie Bree: 

ghar *arev |): 

{ 

/* DOSCREATETHREAD arguments */ 


char far *new_stack; 
unsigned thread_id; 
unsigned return_code; 
unsigned i; 


unsigned ret; 


/* allocate stack for the new thread, stack size = 4000bytes */ 

/* 80286 stack grows down but function malloc() returns a 
pointer to the bottom of the stack */ 

/* So to establish the correct pointer to the top of stack you 
need to add the returned stack pointer with the size of 
the stack */ 


if ((hew stack = (char far *)} malloc (STACK SIZR)) = OG) 4 
printf£(“\nStack allocation for new thread, malloc(), not 


suceessful”) 
DOSEXIT(1,1): 
} 


new_stack += STACK SIZE; /* put the pointer to the top of 
etack */ 


/* g@tart another thread */ 
printf ("\nCreating Thread 2”); 
if (return_code = DOSCREATETHREAD (thread2, 
(unsigned far *) &thread_id, 
new_stack) ) 


printf(“*\\nDosCreateThread failed: %u”,return_code) ; 
DOSEXIT(1,2); 
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for (1 = 0 4 < Se a¢¢) { 


} 


ret = DOSSEMREQUEST((long)&Semaphore, WAIT); 

if (ret) { 
printf(“\nDosSemRequest failed: %d”,ret); 
break; 

Modify_Total_Record( 1 ); 


DOSSEMCLEAR ((long) &Semaphore) ; 
DOSSLEEP ( (long) 20) : /* sleep for a few tick allowing */ 
J/* O8/2 to dispatch the next thread */ 


DOSSEMWAIT( (long )&Complete, WAIT); 


DOSEXIT(1, 0) : 


/* thread 2 first set the complete semaphore indicating that it 
is running and clear the semaphore when it’s about to be done */ 


/* it also will request control of the semaphore to modify the 


total record */ 


void far thread? () 


{ 


Int Pet, 13 
DOSSEMSET( (long) &Complete) ; 


for Gi = 0F aq Sy gee 7 

ret = DOSSEMREQUEST((long)&Semaphore, -1); 

if (ret) { 
printf(“*\nDosSemRequest failed: %d”,ret); 
break; 

} 

Modify_Total_Record( 2 ); 

DOSSEMCLEAR ((long) &Semaphore) ; 


DOSSLEEP( (lone) 20): /* sleep for a few 
tick allowing */ 


/* 08/2 to dispatch the next thread */ 
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DOSSEMCLEAR( (long) &Complete) ; 


DOSEXIT(O,0}: 


void Modify_Total_Record (value) 
unsigned value; 
{ 
Total_Record = value; 
printt (“\nTotal Reeord: %d”,Total Record) ; 


Using Semaphores for Signalling 


Earlier in this chapter we discussed the use of semaphores for mutual exclusion 
and synchronization. Those semaphore related functions have been discussed in 
preceding sections; this section explains how to use semaphores for interprocess 
signaling. 

The previous uses of semaphores already involved signalling. However, in 
addition mutual exclusion and synchronization involve execution control. At the 
beginning of the chapter we discussed the use of flags for interprocess signalling, 
but flags cannot be used for signalling among threads within the same process. For 
signalling within the same process, global variable and RAM semaphores must be 
used. 

Signalling is the sending of messages between processes or threads. It can be 
implemented by having a thread check the values of a variable if the message is 
complex, or the state of a semaphore if the message is simple (“X has occurred”). 

In order to use asemaphore for signaling a thread can set or clear it to represent 
the occurrence of a event. Another thread wishing to monitor the state of this 
semaphore can use any of the semaphore waiting functions with option TimeOut=0, 
which means the calling thread does not wait for the semaphore to be in either the 
set or the clear state. For example, if DosSemWait is used with 7imeOut=0, error 
#12] isreturned if the semaphore is set. If the function is clear the function returns 
normally. ‘The protocol is the same for any semaphore waiting function. Refer to 
the previous sections for a discussion of the issues involved in the use of each type 
of function. 
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Data Transfer Between Processes 


The functions that allow tranfer of data between processes represent the most 
advanced interprocess capabilities provided by OS/2. In its simplest form, 
interprocess data transfer entails one process sending a stream of data to another 
process. Ina more complex instance, data transfer can involve multiple processes 
sending data to one receiving process. No matter what its form, a viable inter- 
process data transfer method must possess the following qualities: it must be able 
to transfer any type of data structure and data format, and the coordination or 
synchronization between the sending and receiving processes should be transpar- 
ent to the programmer—the programmer should not have to deal with the 
problems of coordination. 

Interprocess data transfer is used by many applications in the PC-DOS environ- 
ment, although its existence is not always recognized by programmers. A good 
example of interprocess data transfer is a desktop publishing program that sends 
a document to a laser printer. Laser printers are usually equipped with their own 
CPUs running a specialized program to process the data sent from the computer. 
The data includes both the document text and printing commands which tell the 
printer how to print the document. Printing commands can include information 
such as font style, font size, shading, graphics, and drawing instructions. 

Other data transfer methods are also available with PC-DOS as well as OS/2. 
Using the command processor, the standard output of a program can be redi- 
rected to be the standard input of another program using the command processor 
pipe method. We discuss this method in Chapter 12. This method, however, is not 
appropriate for applications requiring data transfer between multiple concurrent 
processes. 

Another way to transfer data between processes is through file I/O. Data can 
be written to the hard disk by one process, and this same information can be read 
by another process. File I/O, however is slow, and coordination between the 
sending and receiving processes 1s difficult. When file I/O is used for data transfer, 
process | writes to the end of the file, and process 2 reads the data. This requires 
a large amount of disk space since the file gets larger as more data is sent between 
the two processes. Such applications are dependent upon the amount of free space 
on the hard drive. If, to conserve disk space, the new data is written over the old 
data once the data is read, then synchronization becomes the issue. The sending 
process needs to know when the data has been read by the receiving process. 
Otherwise data will be destroyed. The programmer needs to set up a signalling or 
mutual exclusion mechanism to ensure data integrity. 

The data transfer techniques discussed to this point are cumbersome, imprac- 
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tical and require much overhead on the part of the application. They are not 
suitable in a multitasking environment such as OS/2 where interprocess data 
transfer may be the norm. Therefore, resources that provide a viable form of data 
transfer are provided by OS/2. These interprocess data transfer resources are the 
pipe and queue. 

Data transfer can also be realized through the implementation of shared 
memory which allows several processes to share the same memory block. This 
method is very much like having global variables between processes (instead of 
within the same process as is usually the case). Under a normal application, a 
global variable is accessible by any thread running under the same process. Any 
thread can change or obtain the value of the global variable. Shared memory 
establishes a global memory block which is accessible to several processes. Any 
process can obtain or change the values in the shared memory block. When several 
processes are allowed to change the values of a variable, mutual exclusion must be 
established among them to ensure that the variable is kept in a consistent state. 


Pipes 


The original concept and implementation of the pipe for interprocess commu- 
nication was introduced by the developers of the UNIX operating system. A pipe 
allows data to be sent to or received from another process as if the process is writing 
or reading from a file respectively. This ingenous concept has proven to be a very 
efficient and versatile means of interprocess data transfer which requires little 
overhead from applications. Since PC-DOS has had a tradition of incorporating 
features of UNIX, it is natural that OS/2 uses pipes for interprocess communica- 
tion. 

A pipe can be viewed like a water pipeline which has several pumps (or 
processes) sending water (or data) through it. At the end of the pipe, there isa 
reservoir (the receiving process). In more formal terms, a pipe is a FIFO data 
stream or a list where the data is inserted at one end and taken out at the other. In 
OS/2, the pipe is implemented as an internal memory buffer which looks like a file 
to the processes which access it. Data is sent to and received from the pipe exactly 
as if it were written to or read from a file. Several processes can write data to the 
pipe but only one process can retrieve data from it. the process that creates a pipe 
is by definition the receiving process; all others can only write to it. Using a pipe, 
an application can set up a pipeline with several processes sending data to be 
received by one process at the end of the pipeline. OS/2 handles all the scheduling 
and synchronization duties when several processes send data to the pipe at the 
same time, so the application does not have to deal with these issues. 
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A pipe is created using DosMakePipe which returns two pipe handles, one for 
the receiving process and the other for the sending processes. The process which 
creates the pipe is automatically the receiving process, and the receiving process 
cannotwrite to its own pipe. The process which creates the pipe with DosMakePipe 
is the only process which can read from it; all others can only write. Only pipe 
handles for writing are inherited by any child processes spawned by the parent. 

The pipe handle is similiar to the file handle but the pipe itself is an internal 
buffer managed by OS/2. This means, the pipe handle can be used with file I/O 
API functions like DosRead and DosWrite (Chapter 10)°, to retrive and send data 
to the pipe, respectively. The application does not have to keep a pipe pointer or 
concern itself with whether the data will be overwritten by another process (as it 
must in file [/O operations). Once the application finishes using the pipe, the pipe 
is closed using the OS/2 file I/O call DosClose with the pipe handle. When all 
processes stop using the pipe by closing their pipe handles, OS/2 deletes the pipe 
resources. | 

Data is sent to the pipe as a data stream (stream of bytes) in FIFO order so the 
first data stream sent through the pipe is the first data stream to be received. 
Suppose process | sends a single letter, “A,” to the pipe, and process 2 then sends 
another letter, “B,” the receiving process first gets the letter “A” and then the letter 
“B.” If the receiving process asks for two bytes at a time, it receives the string “AB” 
with first byte sent, “A,” in front of the second byte sent, “B.” 

A record format can be imposed on pipe I/O the same as with file I/O by 
sending and retrieving one block of data at a time. Process | can send 20 byte 
records. OS/2 writes the 20-byte block onto the pipe as a data stream consisting 
of 20 bytes. The receiving process must request a 20-byte data block to receive the 
correct data record. The sending process and receiving process must predefine 
the record size beforehand to synchronize the sending and the receiving of data. 
Otherwise, the sending and receiving process will be out of sync with each other 
and the data records sent will not be interpreted correctly by the receiving process. 

By predefining the record size, data structures of the same size can be sent and 
received without much coordination from the sending and receiving process. 
Since the pipe is implemented as a data stream, a method to assure the synchro- 
nization between the sending and receiving process is needed as part of the 
application when those processes need to send data records varying in size and 
type. Suppose the sending process sometimes needs to send a data structure 20 
bytes long, and sometimes it needs to send a different data structure 10 bytes long. 
A mechanism must allow the receiving process to determine which type of record 


*These functions are similiar to functions WRITE() and READ() available with the C run-time library. 
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it is receiving so it can request the appropriate size. We suggest sending a variable/ 
record asa header before the actual record. The header can be a standard size and 
consist of the length of the coming record and/or the data record type. The 
receiving process first reads the header variable off the pipe to determine the type 
of the following record, then retrieves the record using the included byte size. 

OS/2 establishes mutual exclusion when several processes attempt to write to 
the pipe at the same time and determines which process will be first. This is a 
function of the priority and time slice of the thread. 

Allin all, the pipe is a versatile mechanism for interprocess data transfer. Its data 
transfer rate is very fast since the data is kept in an internal memory buffer by 
OS/2. A pipe, however, has its limits. The maximum pipe size is approximately 
64K". This 64K limit represents the largest amount of data the pipe can hold at any 
time. When a process retrieves data from the pipe, it is discarded or taken off of 
the pipe. And when a process writes data to the pipe, the data is added to it. The 
size of the pipe is adjusted accordingly by OS/2. 

Two factors constrain the performance of DosWrite and DosRead when per- 
forming I/O on a pipe: the sending process must wait if there is not enough room 
to write to the pipe, and the receiving process must wait if there is not enough data 
in the pipe for it to read. Since the pipe size is limited to 64K, when the pipe is full 
the sending process (using DosWrite) has to wait until the retrieving process has 
read enough data off the pipe to permit the addition of new data. A similiar 
problem occurs when the pipe is empty, and the reading process (via DosRead) 
waits until enough data is on the pipe to satisfy the read request. If the receiving 
process requests 20 bytes from the pipe, and only 10 bytes of data is available, the 
receiving process then waits until 10 more bytes are forwarded by the sending 
processes. 

The process can also use the asynchronous file I/O functions, DosReadAsync 
and DosWriteAsync (Chapter 10), to asynchronously read and write data to the 
pipe. Because these functions execute concurrently with the calling thead, they 
free it to do other tasks when the pipe is empty or full (though naturally no data 
flows at these times). The calling thread does not have to wait for the completion 
of the reading and writing of data to do other things. These functions also have 
timer services that allow the calling thread to time-out when there’s no data in the 
pipe or the pipe is full for a very long time. These functions are described in detail 
in Chapter 10, File and Device I/O Functions. 

OS/2 keeps track of the size of the pipe and the data using two pointers, Next_In 


464K bytes minus 32 bytes (used by OS/2). This limit is directly related to the segmented memory architecture 
of the 80286 CPU which can only address a 64K segment of memory. 
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and Next_Out. Next_In points to the location of the pipe where the data will be 
added next. When a retrieving process retrieves data from the pipe, Next_Out 
points to the location of the pipe where the data is to be read from. Next_Out 
always points to the next group of data to be read or to the beginning of the pipe 
since data is discarded from the pipe once it is read. 


DosMakePipe 


DosMakePipe establishes a pipe for the calling process. The calling process is 
always the receiving process. Two pipe handles, one for reading and one for 
writing, are returned to the calling process. The pipe handles are inherited by any 
child processes of the calling process. If other processes also need to use the pipe, 
the pipe handle used for writing must be sent to them. Pipe handles can be passed 
to other processes either by a shared memory segment, or as arguments in the 
function DosExecPgm when a child process is created. Function DosQHand Type 
can be used by the child process to determine whether a handle is a pipe handle 
or not. 

DosMakePipe also asks for an estimated pipe size. OS/2 uses this figure to 
allocate as efficiently as possible the memory needed for the buffer. If the process 
needs a larger pipe during execution-time, OS/2 automatically increases the size 
of the pipe up to the 64K limit. 


DosMakePipe (ReadHandle, WriteHandle, PipeSize) 


unsigned far *ReadHandle; /* address of the read handle to be 
returned by OS/2 */ 
unsigned far *WriteHandle; /* address of the write handle to be 


returned by OS/2 */ 
unsigned PipeSize; /* advisory pipe size */ 
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Example One 


,* PRECV.C - Pipe Receiving Process 


This program demonstrates how to use pipe for interprocess com- 
munication. There will be two processes involved in this data 
transfer operation. The first process creates the pipe using 


DOSMAKEPIPE 


which returns a read and a write handle. The sending process 
will use DOSWRITE to send data, and the receiving process will 
use DOSREAD to receive data. 


The second process, PRECV.EXE, will be created using DOSEXECPGM. 
The read and write handles will be passed as arguments. 


Notice that both processes know in advance the size of each data 
element sent to the pipe as well as the number of elements that 
will be transferred. 


i 
include <stdio.h> 
#Finclude <doscalls.h> 


4t}define BUFLEN 50 


main() 
{ 
/* data for DosExecPem */ 
char ObjNameBuf [BUFLEN] ; /* buffer for ObjNameBuffer */ 
char arg[BUFLEN] ; /* eroument burfaer */ 
struct ResultGodes ReturiGedes:/* return code structure */ 
char PgmName[BUFLEN] ; /* program name */ 
unsigned ExecFlags; /* execution flag */ 
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/* data for DOSMAKEPIPE */ 


unsigned ReadHandle; /* Pipe Read Handle */ 
unsigned WriteHandle; /* Pipe Write Handle */ 
unsigned PipeSize; /* Pipe size */ 


/* ether data *i 
unsigned ret; /* ferurm code */ 
unsigned i; 
unsigned value; 


unsigned BytesWritten; /* use for DosWrite */ 


unsisned Child. Status; /* Use for DOSCWAIT */ 
unsigned ID; 


printf(“\nCalling DosMakePipe “):; 


PipeSize = 4096; (* pipe Sige is 4k */ 

ret = DOSMAKEPIPE ((unsigned far *) &ReadHandle, 
(unsigned far *) &WriteHandle, 
PipeSize) ; 

if (ret) { 
oriwtt(“\nError Creatine Pipe, Error Code 

<Ka rh” , Fat): 

DOSEXIT(0,0); 


strcpy(PgmName,”PRECV.EXE”); /* program name of 
receiver */ 
/* putting the Read Handle in the argument string */ 
strcepy(arg,PgmName) ; 


sprintf (argtstrilen(arg)+1,” %d\0",ReadHandle) ; 


ret = DOSEXECPGM ((char far *)ObjNameBuf, 


BUFLEN, 
ie /* Asynchronous Execution */ 
are, /* arpument */ 
NULL, §* null engptr */ 
&ReturnCodes, 


PgmName) ; 
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1£ (¥et) | 
printt(*\nerror Greating Child Process, Error Goede 


(ae? Pet). 
DOSEXIT(0,0) : 


for (2 = Oy a. < 105 ate) 1 /* gendings arbitrary data */ 
value = afl: 
ret = DOSWRITE (WriteHandle, 
(char far *)évalue, /* galue sent */ 
sizeot (value), 
&BytesWritten) ; 
= (eet) 4 


Srint?(“inkrror Weiting Data te Pape, Error 


Code <%d>", ret): 
DOSEZIT (1,0): 
} 
DOSSLEEP(100L); 
} 


printf(*\nSending Process: Stop Sending Data”): 


printf(“\nWait until the child process complete”) ; 


DOSCWAIT (0, /* aetion code */ 
0, (* Wate Option */ 
&Child Status, /* reatirn code of the «child */ 
&ID, /* PID returned */ 


ReturnCodes.TermCode_PID):/* PID of Child Process */ 
printf(“\nand Close the pipe”); 
/* close the pipe */ 
DOSCLOSE(ReadHandle) ; 
DOSCLOSE(WriteHandle) : 


DOSEXIT (1,0): /*-terminate */ 
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i? PRECV.C - Pipe Receiving Process 


This program demonstrates how to receive data from a pipe using 
DOSREAD. 


There are two processes involves in this data transfer opera- 


tion. The first process creates the pipe using 
DOSMAKEPIPE 
which returns a read and a write handle. The sending process 


will use DOSWRITE to send data, and the receiving process will 
use DOSREAD to receive data. 


Notice that both processes know in advance the size of each data 
element sent to the pipe as well as the number of elements that 
will be transferred. 


*} 
+include <stdio.h> 
include <doscalls.h> 


main(argc,argv) 
int aree: 
ehar *arev| |; 


int ReadHandle; /* Pipe Read Handle */ 
f* other data. */ 
unsigned ret; /* return eode */ 


unsigned i; 


unsigned BytesRead; /* use for DosRead */ 
unsigned val; /* yalue receive */ 
printf (” vo Entering Receiving Process “); 


if lavec < 2) 4 
printf(“\nNeed to send Pipe Read Handle”) ; 
DOGEXIT(O, 6): 
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sscanf(argv[1],”%d”, &ReadHandle) ; 


iO hope i alg gt Ma Read Handle: <%d>”,ReadHandle) ; 
for (4 = Of i < 107 21+) { /* gending arbitrary data */ 
ret = DOSREAD (ReadHandle, 
&val, alee Saar J 
sizeof(val), 
&BytesRead) ; 
if (ret) { 


printt(“\nError Reading Data from Pipe. Error 
Code <%d>”, ret); 
DOSEXIT(1,0); 
PELE CH Data Receive: Element: %d Value: 
Me.” Wal) 4 
DOSEXIT(1,0) ; /* terminate */ 


Example 2 (with redirection via DosDupHandle) 


pe PSEND2.C - Pipe Sending Process 


This program is similiar to example #1, but the receiving proc- 
ess will not be aware that it is receiving data from a pipe. It 
will simply read data from STDIN. 


This program demonstrates how to use pipe as a form of inter- 
process communication. There will be two processes involved in 
this data transfer operation. The first process creates the 
pipe using 


DOSMAKEPIPE 


which returns a read and a write handle. The sending process 
will use DOSWRITE to send data, and the receiving process will 
use DOSREAD to receive data. 


The second process, PRECV2.EXE, will be created using DOSEX- 
ECPGM. 
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The first process will duplicate the pipe read handle as STDIN 
using DOSDUPHANDLE. Because each child process inherits the 
handles of the parent process, the receiving process, once 
spawned, will assume that the pipe read handle is the STDIN 
handle. 


Notice that both processes know in advance the size of each data 
element sent to the pipe as well as the number of elements that 
will be transferred. 


Also the receiver or the child process cannot inherit the write 
handle. Because if the sender closes the write handle of the 
pipe, the child process will hang, because it still has the 
input handle of the pipe. Using function DosQFHandState and 
DosSetHandState, we can mask the write handle of the pipe as 
uninheritable by the child process. 


There are several functions in this example which we have not 
introduced. DosDupHandle associates a handle to an opened file 
(Chapter 10). DosQFHandState and DosSetHandState determine and 
set the status of a handle (Chapter 11). DosDupHandle is simil- 
iar to C-Run time library functions Dup() or Dup2(). 


ey 
+#include <stdio.h> 
include <doscalls.h> 


#t}define BUFLEN 50 

#tdefine STDIN 0 

#define LPSTR char far * 

ehar string |] = “abedefahi4* : /* use for DoseWrite */ 


main() 


{ 
/* data for DosExecPgm */ 


char ObjNameBuf [BUFLEN] ; /* buffer for ObjNameBuffer */ 
char arg[BUFLEN] ; /* arpument buffer */ 

struct ResultCodes ReturnCodes;/* return code structure */ 
char PgmName[BUFLEN] ; /* program name */ 


| /* there is no environment buffer */ 
unsigned ExecFlags; /* gmecutadon tflae */ 
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/* data for DOSMAKEPIPE */ 


unsigned ReadHandle; /* Pipe Read Handle */ 

unsigned WriteHandle; /* Pipe Write Handle */ 
unsigned PipeSize; /* Pipe size */ 

unsigned newstdin; /* use for DOSDUPHANDLE */ 
unsigned FileHandleState; /* use for DOSQFHANDSTATE */ 


/* & DOSSETQFHANDSTATE */ 


/* other data */ 
unsigned ret; /* return code */ 
unsigned i; 
unsigned value; 


unsigned BytesWritten;: /* use for DosWrite */ 


ingsiened Child Status: /* Uge for DOSCWAIT */ 
unsigned ID; 


printf(“\nCalling DosMakePipe “); 


PipeSize = 4096: /* pipe sige ite 42K *f 
ret = DOSMAKEPIPE ((unsigned far *) &ReadHandle, 
(unsigned far *) &WriteHandle, 
PipeSize) ; 
if (ret) { 
orinti(*\nError Creating Pipe. Error Code 
<md>”, ret) ; 
DOSEXIT (0,0): 


ret = DOSQFHANDSTATE(WriteHandle, (unsigned far 
*) &FileHandleState) ; 

if (ret) 

printf(“QFHANDSTATE of WriteHandle failed\n”) ; 
FileHandleState & Ox7F88; /* Mask bits not use by call */ 
FileHandleState |= 0x080; /* deny inheritance to 

receiver */ 

ret = DOSSETFHANDSTATE(WriteHandle, FileHandleState) ; 
if (fet) 
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printf(“Set WriteHandle State failed, ret = 
%x\n",ret) ; 


strcepy (PgmName, ”PRECV2.EXE”) ; /* groeram name of 
receiver */ 


/* putting the Read Handle in the argument string */ 


newstdin = STDIN; 
DOSCLOSE (newstdin) ; /* elesé® the original STDIN */ 


DOSDUPHANDLE (ReadHandle, &newstdin);: 


ret = DOSEXECPGM ((LPSTR)ObjNameBuf, 


BUFLEN, 

lig /* Asynchronous Execution */ 
(LESTRINULL, /* argument */ 
(LPSTR) NULL, /* alt eorpote *f 
&ReturnCodes, 

PgmName) ; 


if (ret) { 
prantr(“*\nError Creating Child Process, Ertor Code 
Gd?" ,f6b) % 


DOSES IT (0,0) : 


ret = DOSWRITE (WriteHandle, /* @and the String */ 
(LPSTR) string. (* value seni */ 
strlen(string), 
(unsigned far *)&BytesWritten) ; 
if (ret) { 
printf (“\nkrror Writine Data to Pipe, Error Code 
hae” Let) * 
DOSEXIT(1,0); 


printf(“\nSending Process: Stop Sending Data”); 


printf(“\nand Closing the pipe”); 
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/* elese the pipe */ 
DOSCLOSE (ReadHandle) ; 
DOSCLOSE (WriteHandle) : 


DOSEXIT(1<0)% /* terminate */ 


pe PRECV2.C - Pipe Receiving Process 


This program demonstrates how a child process can receive data 
from a pipe created by its parent process. The child process 
does not know that it is reading data from a pipe. As far as 
the receiving process is concerned, it is reading data from the 
STDIN predefined by the C run-time library. 


There are two processes involved in this data transfer opera- 


tion. The first process creates the pipe using 
DOSMAKEPIPE 
which returns a read and a write handle. The sending process 


will use DOSWRITE to send data, and the receiving process will 
use getchar() to receive data one byte at a time. 


Notice: stdin ie defined in <stdio.h> 


Use stdin with C run-time library function only. Don’t use 
handles opened by the C run-time library with DOSREAD or 
DOSWRITE. 


DOSREAD or DOSWRITE works only with handles opened by DOSOPEN. 


| 

include <stdio.h> 
include <io.h> 
Finclude <doscalls.h> 


main(argc,argv) 
Int arge % 
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char “arsy([]: 


{ 


char ec; /* use for getchar() and putchar() */ 
printf(“\n Receiving: “); 

ery hs 

while (c != EOF) { 


c = getchar(); 
putchar(n); 
} 
print? ("in"): 
DOSEZIT(1.0) + /* terminate */ 


Chapter 4 


Memory Management 
Concepts and Functions 


location of system memory. A block of memory is considered allocated 

when an application takes it from OS/2, and deallocated, or freed, when 
the memory is returned to OS/2 for future allocations. Memory management is 
something that most application programmers would rather not deal with. When 
using high level languages like C or Pascal, programmers tend to let the compiler 
handle memory management. Such high level languages require that all variables 
be declared in advance. Before such a program is executed, enough memory is 
allocated to handle the declared variables and arrays within the program. 

Preallocating memory, however, results in the problem of over-allocation. For 
example, the compiler always allocates enough memory to handle the maximum 
number of elements declared for an array. Ifa program does not fill up its arrays, 
as is often the case, large memory segments are declared but never used by the 
program. To eliminate this wasteful practice, most applications allocate memory 
dynamically, using C library functions like alloc() and malloc() when extra 
memory is required and free() to release the memory block when it’s no longer 
needed. 

Compiler memory allocation functions, however, cannot be used when an 
application needs to share memory segments across processes. Moreover, these 
compiler-implemented functions are often inefficient at managing system mem- 
ory. For assembly language and C programmers who want to manage application 
memory, OS/2 provides a complete set of memory allocation functions for 
managing single segments, or multiple segments, of private or shared memory. 

In a multitasking environment with multiple applications running, memory 
quickly becomes a scarce resource. The performance of the application becomes 
dependent upon the amount of available memory in the system and on the manner 
in which the operating system uses this memory. Therefore, more than a working 
knowledge of the available memory management functions provided by OS/2 is 


Mi anaging memory for OS/2 applications involves the allocation and deal- 
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needed to manage memory efficiently, especially for complex applications like 
databases, spreadsheets, or word processors. In addition, the programmer needs 
to know exactly how OS/2 manages system memory to make optimal use of 
memory management functions in developing high performance applications. 

With these requirements in mind, this chapter discusses the differences be- 
tween physical and virtual memory, how OS/2 implements virtual memory, and 
API functions for memory allocation. We discuss only the memory management 
issues that affect the performance of an application, while Chapter 19 discusses in 
detail how OS/2 uses the features of the 80286 CPU to implement a protected 
virtual memory and multitasking operating system. 


System Memory 


System memory is the amount of random access memory (RAM) installed in a 
system. The maximum amount of RAM an 80286-based system can handle is 
16MB. This is an improvement over 8086/8-based systems which allow for a 
maximum of 1 megabyte of RAM, of which only 640K is directly available for DOS 
and its applications. By utilizing the hardware features of the 80286, OS/2 and its 
applications can access all 16MB of available system memory. 


Virtual Memory 


The 80286 CPU architecture supports the implementation of virtual memory: 
this allows an application to address memory locations that do not necessarily 
correspond to actual locations in physical memory. When an application tries to 
access a virtual memory address, the CPU automatically translates the virtual 
address into an actual location on physical memory. 

With the 8086/88 CPU, memory is addressed directly using a segment register 
and an offset in the following format: segment:offset which directly corresponds 
to a physical memory location. Under the 80286 virtual addressing scheme, 
memory is addressed through a selector:offset. This new format is used by 
applications in the same way as the 8086 addressing format, except that the 
segment register or (the selector) does not point to a physical address but to a 
descriptor located on a descriptor table which contains many descriptors. Using 
this descriptor, the CPU obtains a virtual address which is then mapped onto a 
physical address in system memory. Virtual memory, a pseudo-address, can 
address a much larger memory space than the actual RAM installed on the system. 
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With the 80286, virtual memory can be as large as | gigabyte. 

Mapping this | gigabyte of memory space onto a much smaller physical memory 
space (640K-16MB) is left up to the virtual memory implementation module of the 
operating system. Since 1 gigabyte is much larger than the largest possible physical 
memory space of 16 megabytes, when running multiple applications, requests for 
memory allocation tend to be greater than available physical memory. ‘This 
condition of storage overcommitment occurs frequently in a multitasking system. 

When a process (call it process 1) needs more memory than is currently 
available in physical memory, OS/2 satisfies the allocation request by moving 
memory segments belonging to another process (call it process 2) from main 
memory to a secondary storage device like the hard drive. Once OS/2 clears 
enough space in physical memory, it can allocate the memory segments requested 
by process 1. Later, if process 2 needs to use its memory segments, OS/2 removes 
segments belonging to another process to the hard drive and replaces them with 
the segments requested by process 2. Allocated memory segments are thus 
swapped between physical memory and the disk drive when the total requests for 
memory allocation exceed the amount of physical address space available. This 
technique for virtual memory implementation is called memory swapping. The 
special files that store swapped-out memory segments on the disk drive are called 
swap-files. 

Because of the memory-swapping technique used by OS/2, the amount of 
virtual memory available is directly dependent on the amount of free disk space 
available for memory swapping. If you have 20 megabytes of available disk space, 
then 20 megabytes is the amount of virtual memory OS/2 can provide for your 
system. OS/2 first utilizes whatever RAM memory is available. However, if you have 
very little RAM memory to work with, then the performance of your virtual memory 
system will be impaired because OS/2 will do an excessive amount of memory 
swapping. Theoretically, OS/2 can provide up to | gigabyte of virtual memory, but 
the system would have to contain a |-gigabyte hard drive (which is not yet 
available). 

OS/2 does not implement memory swapping willy-nilly. The description above 
is very cursory. OS/2 uses special methods to implement memory swapping in the 
most efficient manner. These methods address such issues as segment motion, 
segment swapping and segment discard using the least-recently-used (LRU) 
algorithm. 

When an application accesses a virtual address not available in physical mem- 
ory, the 80286 generates an exception condition, “Segment Not Present” (vector 
11). OS/2 then traps this exception to handle the problem of storage overcom- 
mitment. First, OS/2 always tries to allocate physical memory to satisfy the request 
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for memory allocation. If no physical memory is available, OS/2 implements 
segment motion to realign physical memory. If segment motion does not obtain 
enough memory, OS/2 uses segment discard and segment swapping to get the 
necessary memory. 

OS/2 itself requires certain amount of physical memory for its own code and for 
maintaining system resources. Installed device drivers also use a certain amount 
of RAM. Whatever memory left after these needs are met is reserved for 
applications. Figure 4.1 explains how physical memory is used by OS/2 in 
protected mode and compatibility mode. 


OS/2 
Applications 


DOS 3.x 
Applications 


Device Drivers 


Compatability 
Box 


\ 


Figure 4.1 OS/2 Memory Map 
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Segment Motion 


Segment motion solves the problem of memory fragmentation. Memory fragmen- 
tation describes the condition of having small blocks of free physical memory 
interspersed among blocks of allocated memory. Alhough the total memory 
available might be larger than a request for memory allocation, the system needs 
to allocate contiguous blocks of memory and cannot use the dispersed blocks to 
honor an allocation request. 

Figure 4.2 illustrates this problem. Originally the system has 100K of memory 
in a contiguous block. Process 1 asks for 30K, then process 2 asks for 30K. Process 
1 then releases 30K. The system now has 70K left in two blocks of 30K and 40K. If 
process 3 asks for 50K, the system cannot allocate this memory even though the 
total available memory is 70K, because the available memory is not in a contiguous 
block. 


_ eallocated 


segment motion 





fails for lack of 


Figure 4.2 Segment Fragmentation. 
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Memory fragmentation is the result of physical memory being allocated in small 
blocks which are then released at random, creating holes of unallocated memory. 
Segment motion removes the small holes of free memory by realigning the 
available memory space into consecutive blocks, creating larger contiguous block 
of free memory. 


Segment Swapping and Segment Discard 


When segment motion has been instituted and the result still does not yield 
enough memory to satisfy the request for memory allocation, OS/2 tries to discard 
some used segments of memory following the Least-Recently-Used (LRU) algorithm. 
This algorithm identifies the segments of memory that have not been accessed 
recently. Itis necssary because swapping segments between physical memory and 
the hard-drive is a slow process. Hence, the operating system always tries to 
minimize the amount of swapping that must be done. The LRU implemention of 
virtual memory is based on the assumption that segments which have not recently 
been accessed by programs will not be accessed in the near future, either, thus 
minimizing the number of times OS/2 will have to swap the segments back into 
memory. 

Recall that each descriptor in an LDT has an access bit for each segment used 
by the process. Whenever a segment is used, this bitis set by the 80286 CPU 
OS/2 periodically checks the access bits of all descriptors, resets the bit, and 
creates a time stamp indicating the last time the segment was used. The LRU 
segments are identified by checking the time stamp. The segments with the oldest 
timestamp become the LRU segments. 

To save the time it takes to write to disk, OS/2 takes steps to perform as little 
actual memory swapping as possible. When the LRU segment is either a code 
segment or a data segment that has not been modified, the segment is simply 
discarded instead of swapped. ‘This is because swapping code segments or 
unmodified data segments is not necessary—the contents of these segments are 
already available on the program (.Exe) files. If these segments are needed, 
OS/2 reads the program files and restores the segments into memory. This 
procedure saves OS/2 half the I/O time it takes to do a full swap. 

If the LRU segments are modified data segments, OS/2 writes the contents of 
the segment onto the file SWAPPER.DAT, located on the disk drive. The segments 
are swapped back into memory if they are needed (resulting in the discard or swap 
of other LRU segments). 
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Config.Sys Parameters for Memory Managment 


Several parameters dictate the virtual memory configuration of the system to be 
defined in the system configuration file, CONFIG.SYS. The values for these 
parameters must be carefully considered because they are crucial in the implem- 
entation of the system virtual memory. The parameters are: memman, rmsize, and 


swappath. 


memman 


rmsize 


swappath 


Defines the memory management options the system 
can use. Options are: 


swap/noswap,move/nomove 


The swap/noswap option determines whether memory 
swapping is enabled or disabled, respectively. ‘The move/ 
nomove option determines whether memory motion 
will be enabled or disabled respectively. 

If the parameter is set as: 


memman ~ Swap,mMmove 


OS/2 uses both memory swapping and segment motion 
techniques when there is not enough RAM to satisfy the 
requests of the application. (Ihe noswap, nomove 
option should be used only for dedicated systems where 
the memory requirements of the applications are known 
in advance.) 


Defines the amount of memory to be allocated for real 
mode or compatibility box applications. This section of 
memory is not available for protected mode application. 
If the parameter is defined as: 


rneize = 640, 


then 640K of physical memory is allocated for the com- 
patibility box application. (Please refer to Chapter 22, 
Compatiblity Mode, for details). 


Defines the directory where the swap file, SWAPPER.DAT, 
is be located. The file SWAPPER.DAT contains the 
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memory segments that were swapped out of memory. 
The size of the swap file can grow as large as the available 
disk space if many memory segments are swapped from 
memory to disk. The format for the parameter is: 


\swappath = [drive] : [\path] 


oe swappath = c:\tmp 


which specifies that the file SWAPPER.DAT will be lo- 
cated on drive C: and in directory\TMP. There is no way 
to delete this file from OS/2. If the swap file grows too 
large, the user can load DOS and delete the file to save 
disk space. 


Memory Functions 


The previous sections of this chapter discuss the ways OS/2 implements virtual 
memory. Since segment motion, segment discard, and segment swapping require 
considerable processing time, it is important to understand how OS/2 uses these 
techniques to determine the performance of the application when memory 
allocation is required. 

This section discusses the API memory functions provided by OS/2 for assembly 
programmers and advanced C programmers to allocate or deallocate memory for 
their applications. ‘These API memory functions can be divided into four 
categories: single segment memory, multiple segment memory, memory sub- 
allocation, and shared segment memory. There are also certain API functions 
which can be used across all categories, such as multiple or single segments like 
DosMemAvail and DosFreeSeg. DosMemAvail returns the size of the largest free 
memory block available. DosFreeSeg deallocates memory segments previously 
allocated by other allocation functions, returning them to the free memory pool. 

Recall from page 166 that memory is addressed in the 80286 CPU according to 
the format of selector:offset. When a memory segment is allocated via single 
segment, multiple segment, or shared segment memory allocation, the value of the 
selector will be returned to the calling process. The process can assume that an 
offset of 0 is the starting offset of the just-allocated memory block. 

C programs should use the selector and offset values carefully. Selector offset 
values must be transformed into pointers before a C program can access any 
memory locations within the allocated segment. ‘Two very useful macros, FP_SEG() 
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and FP_OFF‘(), available with most popular C compilers, transform a selector offset 
combination into a pointer. (See the sample programs in this chapter for usage 
of these functions). 

There are predefined limits to the number of shared and non-shared segments 
the operating system can handle at the same time. These limits, however, are very 
large. Unless the application uses memory with extreme inefficiency, these limits 
are not going to affect any applications. OS/2 can handle 7680 memory segments 
in the whole system at the same time. This includes both shared and non-shared 
segments. A maximum of 2000 swappable segments, 6144 shared segments, or 
2048 non-shared segments can be allocated at the same time. OS/2 recommends 
that each application should allocate a maximum of 300 shared segments, 10 
named shared segments (via DosAllocShrSeg) or 100 non-shared segments at the 
same time. (Please note that these limits might change in future releases of the 
system.) 


Useful Memory Functions 


The three memory functions discussed so far do not fall under any of the 
categories that were set forth. FP_SEG() and FP_OFF‘() assign a selector and offset 
toaC pointer. These functions are C run-time library functions, and are not part 
of OS/2. Their use, however, is crucial for addressing allocated memory segments. 
We have included an example of their use below as well as in the programming 
examples in this chapter (please refer to your C compiler manual for their exact 
syntax). DosMemAvail is an OS/2 function, which allows a process to determine 
the amount of free memory available to it. 


FP_SEG() and FP_OFF() 


The selector and offset of a memory block allocated by any of the functions in 
this chapter can be assigned to a pointer using the two macros FP_SEG() and 
FP_OFF. The following section of code demonstrates how to use the two macros. 


char far *addr; /* address to be assigned to the sub 
allocated block */ 

unsigned selector; /* selector to be assigned via 
DosAllocSeg */ 

unsigned offset; /* offset to be assigned via 


DosSubAlloc */ 
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/* assume that the value of selector was 
returned by DosAllocSeg */ 


/* also assume that the value of offset 
was assigned by DosSubAlloc */ 


/* addr, then can be assigned to point to 
the start of the allocated memory 
block using the following code */ 


FP_SEG(addr) = selector; /* assign the selector value */ 
FP_OFF (addr) = offset; /* and the offset value of the block */ 
DosMemAvail 


DosMemAvail determines the largest unallocated block of memory available in 
the system. Applications should use DosMemAvail to determine whether a request 
for memory allocation will be satisfied immediately or whether the process must 
wait for OS/2 to perform segment motion, segment discard, or segment swapping 
because memory is overcommitted. DosMemAvail returns the size of the largest 
free memory block the instant the function is executed. But remember, the size of 
the largest unallocated memory block may change at any moment because of the 
activities of other processes in the system. DosMemAvail does not return the total 
amount of free memory available on the system, but rather the largest block of free 
memory. The total amount of free memory can be determined only after segment 
motion is performed by OS/2. 


DosMemAvail (MemAvailSize) 


unsigned long far *MemAvailSize; = /* address to store the value of the 
largest size */ 





Single Segment Memory Functions 


Single segment memory functions let an application allocate, deallocate, and 
reallocate single blocks of memory that can be as large as an entire physical 
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memory segment (64K). The limit of 64K is imposed because physical memory is 
divided into 64K segments by the 80286. Three functions are available. DosAl- 
locSeg allocates a block of memory with the maximum size of 64K. OS/2 returns 
the selector of the block to the calling thread. The selector allows the program to 
manipulate the memory block or acts as a required parameter for other functions 
(for high-level languages). DosReallocSeg changes the size of a previously 
allocated memory block (via DosAllocSeg). DosFreeSeg deallocates the previously 
allocated memory block. 

Although there are separate functions for sharing memory, the programmer 
must decide in advance how the segment is to be shared by setting the appropriate 
usage parameters when allocating memory with DosAllocSeg. Sharing a block of 
memory previously allocated by DosAllocSeg requires the use of either Dos- 
GiveSeg or DosGetSeg, which are discussed on pages 208-224. 

A memory segment can be declared as discardable, telling OS/2 that it can be 
erased when the available physical memory is low in the system and extra memory 
is required (i.e., during storage overcommitment). A segment should only be 
declared as discardable if it is not used frequently, or is unused for a long period 
of time. Such a segment should also be easily regeneratable, in case the process 
needs to use it again after it has been discarded. Discardable memory blocks can 
be used to enhance the performance of the application. But the time required to 
recreate the segmentifitis needed again should be considered before itis declared 
discardable. 

To ensure that a discardable segment is not discarded while it is in use, the 
thread that is using it can temporarily lock the segment with DosLockSeg. 
DosLockSeg notifies OS/2 that the segment is currently non-discardable. If extra 
memory is needed, OS/2 can still perform segment motion or segment swapping 
on the segment, but it cannot discard it. When the segment is no longer needed 
by the application, it can be unlocked with DosUnLockSeg. 


DosAllocSeg 


DosAllocSeg allocates a block of memory to the requesting process. The 
maximum size of the blockis a single segment of 80286 memory, which is 64K. The 
requesting process must provide the size of the block, an address for the selector 
of allocated memory block, and the usage options for the allocated memory block. 
DosAllocSeg returns the selector of the allocated memory block for access to the 
block and as a parameter for other API memory functions. 

Once the memory block is allocated, it is owned by the requesting process. An 
owner process can share the memory block with other processes. Function 
DosGiveSeg allows the owner process to let another process share a memory block. 
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Function DosGetSeg allows another process to share a memory block owned by 
another process. These sharing options are set using the Allocflags parameter. 
This parameter is a bit mask value which allows a segment to be declared as sharable 
via DosGiveSeg, DosetSeg (or both ), or not sharable. It also governs whether or 
not a segment is discardable. 


DosAllocSeg (Size, Selector, AllocFlags) 


unsigned Size; /* size of memory block in 
number of bytes */ 

unsigned far “Selector; /* pointer to the selector of the 
memory block to be returned 
by OS/2 */ 

unsigned AllocFlags; /* usage option for the memory 


block */ 
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Real Mode Restriction 


DosAllocSeg is very much like function 48H of DOS interrupt 21H. This 
function has two differences in the compatibility mode: the size of the memory 
block will be rounded up to fit into the next paragraph of memory; and, the 
selector returned is the actual segment address of the physical memory block. 


DosLockSeg and DosUnlockSeg 


DosLockSeg allows a process to declare a discardable memory segment undis- 
cardable until DosUnlockSeg is issued. Once locked, the memory segment can be 
moved or swapped but cannot be discarded. Once unlocked, the memory segment 
is again discardable. 

A discardable memory segment should be created by the process to hold 
temporary information that is to be used only a few times and within a short period 
of time. The information stored on the segment should also be easy to recreate © 
should the segment be discarded. Once declared as discardable, the segment will 
be discarded by the OS/2 memory manager whenever situations of storage 
overcommitment arise. 

A memory segment is considered discardable if bit 2 of the AllocFlags parame- 
ter is set when the segment is allocated using DosAllocSeg. If DosLockSeg or 
DosUnlockSeg is called with a selector of a undiscardable memory segment, an 
error occurs, indicating that the segment is not a valid discardable segment. 
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When a segment is discarded by OS/2, the subsequent call of DosLockSeg 
returns error, # 157. The thread has to reallocate the segment using DosReal- 
locSeg as well as to recreate the contents of the segment. 

DosLockSeg can be used recursively or nested. This allows the process to lock 
a segment multiple times without issuing DosUnlockSeg. But for every DosLock- 
Seg issued, a corresponding DosUnlockSeg has to be issued (e.g., five lock calls 
require five unlock calls) to unlock the segment. If DosLockSeg is issued 255 times 
on a single segment, the segment will be permanently locked. No subsequent 
DosUnlockSeg will effect this segment’s locked state. 

Both functions, DosLockSeg and DosUnlockSeg, require the selector of the 
memory segment that is to be locked or unlocked. The selector is the value 
returned when the segment was allocated either by DosAllocSeg or DosReAI- 
locSeg. 


DosLockSeg (Selector) 


DosUnlockSeg (Selector) 


unsigned selector; . /* selector of the segment to be locked 
or unlocked */ 





Example: 


unsigned Selector; /* selector returned by memory 
alloc: finetion *7 


DosLockSeg (Selector); 


DosFreeSeg 


DosFreeSeg deallocates a segment which was allocated using DosAllocSeg, 
DosAllocHuge, or DosAllocShrSeg. Both shared and non-shared memory blocks 
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can be deallocated using DosFreeSeg. The resources for a shared segment, 
however, will be maintained by OS/2 until the last process that has access to the 
segment issues the function DosFreeSeg. For shared segments, an internal count 
is kept by OS/2. It is incremented whenever the shared segment is shared by an 
additional process, and decremented whenever the segment is deallocated by a 
process. When this internal reference count reaches zero via DosFreeSeg, this 
means that no other process is sharing the segment, and it is deallocated. 


DosFreeSeg (Selector) 


unsigned selector; /* selector of the segment to be 
deallocated */ 





DosReAllocSeg 


DosReAllocSeg changes the size of a previously allocated memory block using 
DosAllocSeg. The largest size the memory block is a single 82086 memory 
segment, which is 65356 bytes (64K). 

The size of both shared segments and unshared segments can be changed using 
DosReAllocSeg. The size of a shared segment can only be increased, not 
decreased. A segment is declared as shared or non-shared using the parameter 
AllocFlags with function DosAllocSeg. 

If the memory block is discardable (if bit 2 of AdlocKlags is set via DosAllocSeg), 
Using DosReAllocSeg also declares the segment temporarily undiscardable, as if 
the function DosLockSeg was also issued for the segment. 


DosReAllocSeg (Size, Selector) 


unsigned Size; /* size of memory block in number of 
bytes */ 
unsigned Selector; /* selector of the segment to be 


changed*/ 
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Compatability Mode Restriction 


DosReAllocSeg in the compatibility mode is very much like function 44H of 
PC-DOS interrupt 21H. The only restriction is that the size of the memory block 
will be rounded up to fit into the next paragraph of memory. The selector of the 
memory block has to be the actual segment address of the block. 


Examples 
/* 
ALLOC.C 
This program demonstrates: 
how to use DosAllocSeg and DosFreeSeg. 
how to grow and shrink the segment using DosReAllocSeg. 


The program first creates a 32K segment. 
increase the segment to 64K 
then decrease the segment to 16K 


ay 

#Finclude <doscalls.h> 
include <malloc.h> 
include <dos.h> 
}tdefine NOTSHARED 0 


void main() 
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unsigned selector; /* selector of the segment*/ 

* /* pointer to memory segment */ 
/* this pointer must ba far */ 
/* because it points to a seement */ 
/* other than the current segment */ 
/* eeinted by DS *7 


ehar tar 


int ret: /* return code */ 


printf (“\nAllocating a 32K segment”) ; 
ret = DOSALLOCSEG((32 * 1024), 
(unsigned far *)&selector, 
NOTSHARED) ; /* segment will not be shared */ 
/* and not diseardable */ 
if (ret) 


99 


printf(“\nDosAllocSeg failed, error code %d bet) 
printf(“\nDetermine the pointer to the segment”) ; 

FP_SEG(p) = selector; /* make long pointer to seg */ 

BE OEE (pp). = Os 


ae /* modify the block content */ 
ib. 

es 

p[3] OF 3 

printf(“\nNew value of the memory block: %Fs”,p); 


plo] 
p[i] 
e124 


{/* tpereace the size to 6ak */ 
printf(“\nIncrease the segment size to 64K”); 
ret = DOSREALLOCSEG((64 * 1024), selector); 
if (ret) 
printf(“\nIncrease segment size failed, error wd”, ret); 


printft(“\nCurrent value of the Memory Block: %Fs”,p); 
printft(“\nDecrease the segment size to 10K”); 


/* iperease the sige to 10K */ 
ret = DOSREALLOCSEG( (10 * 1024), selector): 
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if (ret) 
printf(“\ndecrease segment size failed, error %d”, ret); 


printf(“\nCurrent value of the Memory Block: %Fs”,p); 
ret = DOSFREESEG(selector) ; 


DOSEXIT (1,0): /* exit */ 


Muiltiple-Segment (Huge Memory) Allocation 


OS/2 applications can allocate memory blocks larger than the 64K limit of a 
single 80286 memory segment. This is done by requesting allocations of multiple 
64K memory blocks. For C programs that allocate multiple segments of memory, 
the medium memory model or any model that allows data segments larger than 
64K should be used to compile programs. To determine the largest possible 
memory block that can be allocated, the process should use function DosMe- 
mAvail to check the size of the largest available memory block. 

A block made up of multiple memory segments can be allocated using DosAl- 
locHuge. A multi-segment block of memory is still accessed with a selector. The 
selector returned by DosAllocHuge, however, only points to the first segment of 
the block. To obtain the selector of the second segment, an increment (derived 
from the shift count returned from DosGetHugeShift) must be added to the first 
selector. The same increment can be added to the second segment to get the third 
segment, and so on. 

The size of preallocated multiple segment blocks of memory can be changed 
using DosReallocSeg. To deallocate a preallocated multiple segment block of 
memory, the process can use DosFreeSeg. 


DosAllocHuge 


Using DosAllocHuge, a multiple-segment block of memory can be allocated to 
a process. The size of the memory block is specified by the number of full 64K 
segments the block contains and the size of the last segment. For example, if the 
process wants to obtain a 266K block of memory, it must specify four full segments 
and an additional segment of 10K. 

DosAllocHuge requires the process to specify the maximum number of seg- 
ments the allocated block of memory might be increased to in the future, using the 
reallocation function DosReAllocHuge. The maximum number of possible seg- 
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ments is specified by parameter MaxNumSeg. If the process does not intend to 
increase this multiple-segment block beyond the original size, MaxNumSeg 
should be set to zero. The memory block, however, can still be shrunk. 

A huge memory block can also be declared as shareable with the function 
DosGiveSeg using the option specified by parameter Flag. Flag is a word bit-mask 
variable, but only the values of the first three bits (0, 1, and 2) are important. 

OS/2 returns a selector to the multiple segment memory block. This selector, 
however, only accesses the first segment of the memory block. An increment value 
must be added to the first selector to obtain the value of the second selector. The 
same increment value can be added to the second selector to obtain the third 
selector. This increment value is used to obtain the selectors for the next n 
segments up to the last segment (where n can be any number up to MaxNumsSeg)). 

The increment value is derived by shifting left the value 1 by the shift count 
which is returned by the function DosGetHugeShift. Suppose the first selector 
returned is 10. The shift count returned is 3. Shifting left the value 1 by the shift 
count, or 3 places, gives us 8. The value 8 is the increment value to be added to the 
first selector to obtain the next selector. Therefore, the value of the second 
selector is 18. The value of the third selector is 26 (18 + 8) and so forth. The 
following demonstrates the process: 


Ist selector=10 (returned by DosAllocHuge) 
shift count = 3 (returned by DosGetHugeShift) 


increment = 1 << shift count 
increment = 1 << 3 
increment = 8 


2nd selector = Ist selector + increment 
2nd selector =10+8 
2nd selector = 18 


3rd selector = 2nd selector + increment 
3rd selector = 26 


etc. 


Actually the value of the selector and shift count is different from the simple 
value used in the example above. In protected mode the shift count is usually 4, 
making the increment 16. Inreal mode the shift countis 12, making the increment 
1000H or the length of a memory paragraph in the 8086 mode. 
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DosAllocHuge (NumSeg, Size_Last_Seg, Selector, MaxNumSeg, Flag) 


unsigned NumSeg; /* number of segments to be allocated */ 
unsigned Size_Last_Seg; /* size of the last segment */ 

unsigned far *Selector; /* pointer to selector to be returned */ 
unsigned MaxNumSeg; /* maximum number of segments that 


might be allocated */ 
unsigned Flag; /* sharing option */ 
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DosGetHugeShift 


DosAllocHuge returns a selector to a huge memory segment. This selector, 
however, can only be used to address the first segment of a multi-segment block. 
To obtain the second segment’s selector, an increment is added to the first 
selector. To obtain the third segment’s selector, the same increment is added to 
the second selector. The increment is calculated by shifting left the binary value 
1 nnumber of places. The value n or the shift count is returned by the function 
DosGetHugeShift. 

For a detailed explanation of how to use DosGetHugeShift, please refer to the 
previous section on DosGetAllocHuge. 


DosGetHugeShift (ShiftCount) 


unsigned far *ShiftCount; /* address to store the value of shift 
count */ 
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DosReAllocHuge 


DosReAllocHuge changes the size of a multiple-segment memory block previ- 
ously allocated with DosAllocHuge. The size of the memory block is specified by 
the number of full 64K segments the block will take and the size of the last segment 
in bytes. For example, if the process wants to obtain a 266K block of memory, it 
has to specify four full segments and a partial segment of 10K. 

DosReAllocHuge can decrease or increase the size of a memory block. The 
largest size of the huge memory block, however, is limited by MaxNumSeg which 
was specified by DosAllocHuge. MaxNumSeg limits the maximum number of 64K 
segments the memory block can be increased to using DosReAllocHuge. 

The new huge memory segment is addressable with the same selector and the 
same increment previously derived from the shift count returned by DosGetHuge- 
Shift. The increment value is obtained by shifting left the value 1 by 7 places or the 
shift count (returned by DosGetHugeShift). Refer to the previous section on 
DosGetAllocHuge for more details on how to address the multiple segments within 
a huge block. 


DosReAllocHuge (NumSeg, Size_Last_Seg, Selector) 


unsigned NumSeg; /* number of segments to be allocated */ 
unsigned Size_Last_Seg; /* size of the last segment */ 
unsigned Selector; /* selector of the first segment of the 


huge memory block to be changed */ 
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Examples 


/* HUGE.C 


This program demonstrates: 
How to allocate a huge segment (a segment 
greater than 64K), using DosAllocHuge and DosFreeSeg. 
How to access the multiple segment using DosGetHugeShift. 
We will also show you how to grow and shrink the huge 
segment using DosReAllocHuge. 


For those of you who are not familiar with the Windows 
environment, we also demonstrate how to copy two far 
pointers. 


=p 


tinclude <doscalls.h> 
include <dos.h?> 


4Kdefine NOTSHARE 0 


void lstrcepy(s.¢1) /* streoy weTrsion Tor char far * */ 
Char tar “6,” 813 /* vou cahnot use any C run-time library */ 
/* Pumetiens for far pointer (char */ 

/* far *), when you compile in the */ 

i? C. 2, 66 M model *y 


char far *t,°tl: /* two temp LPSTR *y 
int i; 
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t =: 

Cl = 214 

1 = os 

while (*tl !=’\0') 
ttt++ = *t14++: 
x oe me 

ee = PVG 


void main () 


/* 
unsigned FirstSelector; /* 

/* 
unsigned SecondSelector:/* 
tinsigned ThirdSelector: /* 


char far *PirlHuseseq;: /* 
char far *Ptr2Hugeses; /* 
ehar far *Ptr3uugeses: -/* 


/* 
Le 
/* 
/* 
int numseg; y* 
int last_sep size; ye 
int max_num_seg; :* 
unsigned ShiftCount; ,* 
Lut Cet; 
numsea = 4; ;* 


last_seg size = 14000; /* 


Max nim ses = /; fe 
/* 
/* 


parameters for DosAllocHuge */ 
first selector of the */ 

huge seg */ 

second selector */ 

third selector */ 


pointer to the let saemernt */ 
pointer to the 2nd segment */ 
pointer to the 3rd segment */ 
all these pointers must be far */ 
becatise they point to another */ 
segment other than the current */ 
segment pointed by DS */ 


number of segment */ 
last segment size */ 
maximum number of segment */ 


parameter for DosGetHugeShift */ 


Total Memory allocated is */ 
64K *4 + last_ees size */ 


the maximum number of segments */ 
the block can ever be increased */ 
to via DosReAllocHuge */ 
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printt (“\nAllocating a “dK bytes segment”, 
(numseg *64)+(int) (last_seg_size/1024)); 

/* allocate a huge segment */ 
ret = DOSALLOCHUGE (numseg, 

last_seg_ size, 

(unsigned far *) &FirstSelector, 

max_num_seg, 

NOTSHARE) ; /* not share and not discardable */ 
if (ret) 

prante(* \nAllocHuse failed, error td”, ret); 


DEINE \Wnbire: Selector: GO4xk",PirestSelector) : 

/* determine the address of the first segment */ 
FP_SEG(PtrlHugeSeg) = FirstSelector; 
FP _OFF(PirlBugeSes) = 0; 


/* modifying the first segment */ 
lstrcepy(PtrlHugeSeg, (char far *)”First Segment”); 
printf(“\n Contents of the first segment: %Fs”, PtriHugeSeg); 


/* determine the address of the second segment */ 


ret = DOSGETHUGESHIFT ((umsiened far *J/&ShiftCount) ; 
if(ret) 
printf(“\nGetHugeShift failed, error %d”, ret); 


SecondSelector = FirstSelector + (1 << ShiftCount) : 
FP_SEG(Ptr2HugeSeg) = SecondSelector; 
FP_OFF(Ptr2HugeSeg) = 0; 

OriAatt ("in wnsShittrteunt: Sd", shireCount) : 
printft(“\nSecond Selector: “04X",SecondSelector) ;: 


/* modifyine the sacond segment */ 
latrepy (char far *)Pir2hueeses, (char fear *)}"Second 
Segment”) ; 


printf(“\n Contents of the second segment: %Fs”,Ptr2HugeSeg) ; 


/* determine the address of the third segment */ 
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ThirdaSelecetor = SecondSelector + (1 <4 Bhi ttCount) - 
FP_SEG(Ptr3HugeSeg) = ThirdSelector; 
FP_OFF(Ptr3HugeSeg) = 0; 


/* modifying the third segment */ 


lstrepy (Ptr3HugeSeg, (char far *)”Third Segment”) ; 
printf(“\n Contents of the third segment 
%Fs”,Ptr3HugeSeg) ; 


/* grow the huge segment to the max number of segment*/ 
printf(“\nIncrease the segment to %dK bytes”, 

(max_num_seg * 64)); 
DOSREALLOCHUGE (max_num_seg, 0, FirstSelector) ; 
if (ret) 

orintt(“\n ReAllocHuee Failed, error Md", rer). 


orinti(*\ Contents of the third seement: “Fs”. Prr3bugesas) : 


/* shrink the huge segment to its orginal size */ 
printt(*\n Shrink the sesement to its original size”): 
DOSREALLOCHUGE (numseg, last_seg_ size, FirstSelector) ; 
it. (ren) 

printf(“\nReAllocHuge failed, error %d”, ret); 


DOSFREESEG (FirstSelector) ; /* free the huge segment */ 


Memory Sub-Allocation 


Memory suballocation is the process by which a large block of memory can be 
partitioned into multiple smaller blocks. It is useful when a program needs to 
rapidly vary the amount of memory it uses over time (to request additional memory 
for new pointers or arrays, to release memory no longer needed, etc.) But using 
memory allocation functions to request or discard memory (DosAllocSeg and 
DosFreeSeg) devours extra CPU cycles. Instead, the programmer may choose to 
do the allocation and deallocation using the suballocation functions DosSubAloc 
and DosSubFree. These allow a programmer to use an already allocated memory 
block like a free memory pool from which smaller memory blocks can be carved 
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out as needed, without using the processor-intensive functions DosAllocSeg and 
DosReAllocSeg. For example, a program can preallocate a 64K block to be used 
as a free memory pool at the beginning of the program. Stacks, new pointers, or 
dynamic memory variables can be suballocated from this memory pool using 
DosSubAlloc without the need to call DosAllocSeg. 

Memory suballocation is not generally an issue in high-level languages since the 
compiler generally allocates enough memory to hold the largest declared in- 
stances of arrays and variables. When dynamic memory is required, functions like 
malloc() and alloc() can be used. Assembly language programmers may wish to 
take advantage of this technique to write code capable of high speed dynamic 
memory allocation (using a minimum of OS/2 function calls). The drawback here 
is that the assembly program will have to take care of its own memory management. 
Also, preallocating memory to anticipate future usage tends to lead to inefficient 
memory allocation because memory blocks are allocated but infrequently ac- 
cessed. 

Before suballocating memory from an already allocated memory block, the 
block must be initialized for memory suballocation with the function DosSubSet. 
Memory suballocation is then performed using function DosSubAlloc. When the 
process no longer needs the suballocated memory block, it can use DosSubFree to 
return the suballocated memory segment to the original memory block from 
which it came. Note that DosSubFree does not release the suballocated memory 
block back to OS/2’s free memory pool, but to the original memory block from 
which it was carved. To free up this memory for use by other processes, the entire 
original memory block must be returned to OS/2’s free memory pool using 
DosFreeSeg. 


DosSubAlloc 


DosSubAlloc suballocates a memory block from a larger memory block already 
allocated with either DosAllocSeg or DosAllocShrSeg. Prior to suballocation, the 
block should be initialized using DosSubSet. 

The largest block that can be suballocated is very close to the size of the 
previously allocated memory segment. Itis the size of the originally allocated block 
minus 8 bytes. These lost bytes are used by OS/2 to track the suballocated blocks. 
For example, if the process allocated 56K using DosAllocSeg, the largest block that 
can be suballocated from this orginal memory block is 56K minus 8 bytes. 

The size of a suballocated block (via DosSubAlloc) can be easily changed using 
DosSubSet. The new size of the suballocated block is also limited to the size of the 
original memory segment allocated by DosAllocSeg or DosAllocShrSeg. A block 
that is larger than the original memory block can be suballocated by changing the 
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size of the original block with DosReAllocSeg, then changing the size of the 
suballocated block using DosSubSet. 

DosSubAlloc expects three parameters: the selector of the original memory 
block (returned by DosAllocSeg or DosAllocShrSeg), a pointer to store the offset 
of the new suballocated block, and the size of the block to be suballocated. The 
size of the block must be a multiple of four. Otherwise, OS/2 rounds off the size 
to the closest integer that is a multiple of four. 

As mentioned in the virtual memory section earlier in the chapter, memory is 
addressed in the format of selector:offset. The suballocated memory block is 
addressed in the same format. The selector is the value returned when the segment 
is allocated by DosAllocSeg or DosAllocShrSeg. The offset, which is returned by 
DosSubAlloc, points to the starting address of the suballocated block. 


DosSubAlloc (SegSelector, BlockOffset, Size) 


unsigned SegSelector; /* selector of segment where memory 
will be suballocated */ 

unsigned far *BlockOffset; /* suballocated block starting offset */ 

unsigned Size; /* size of the suballocated memory 


block */ 
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Example 


unsigned Selector; 
unsigned BlockOffset; 


char Tear “p- 
DOSALLOGSEG((32 *1024), f® BOK *y 
(unsigned far *)&Selector, 


ope 


DOSSUBALLOC (Selector, (unsigned far *) &BlockOffset, 
(10 *1024)):/* suballocate 10K of memory */ 


FP_SEG(p) = Selector; /* get up p to point to stiballoecated *s/ 
FP_OFF(p) = BlockOffset; /* memory block */ 
DosSubFree 


DosSubFree returns a suballocated memory block to the original memory 
segment from which it was suballocated. DosSubFree works only with memory 
blocks suballocated using the function DosSubAlloc. DosSubFree does not return 
the memory segment to the available memory pool kept by OS/2. To return 
memory to the system at large the process must use DosFreeSeg. 

DosSubFree expects three parameters: the selector of the original memory 
block (returned by DosAllocSeg or DosAllocShrSeg), the offset of the suballocated 
block that is to be returned to the orginal memory segment, and the size of the 
block. The offset of the memory block must be the same as the offset returned 
when the block was suballocated using DosSubAlloc. Since the size of the 
suballocated memory block must be a multiple of four, the size specified by 
DosSubFree must also be a multiple of four. For effective memory management, 
itis best for the size of the block to be the same as when the block was suballocated 
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using DosSubAlloc. Ifthe size specified by DosSubFree is smaller than the original 
size, the memory block which makes up the difference is not deallocated, and is still 
usable by the process. 

If the size specified by DosSubFree is larger than the original size of the 
suballocated block, OS/2 returns error 312, indicating that the specified block has 
overlapped with unallocated memory. 


DosSubFree (SegSelector, BlockOffset, Size) 


unsigned SegSelector; /* selector of segment where memory is 
| suballocated */ 

unsigned BlockOffset; /* suballocated block starting offset */ 

unsigned Size; /* size of the suballocated memory 


block */ 
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Example 


unsigned Selector; 
unsigned BlockOffset; 
unsigned Size; 


char Tak “Dp: 


DOSALLOCSEG((32 *1024), y® 32K #4 
(unsigned far *)&Selector, 
0 


Sige = 10 * 1024: 
DOSSUBALLOC (Selector, (unsigned far *) &BlockOffset, Size); 
/* sguballocate 10K of memory */ 


FP_SEG(p) = Selector; /* get up p te point to suballocated 
FP_OFF (p) BlockOffset ; /* memory block */ 


DOSSUBFREE(Selector, BlockOffset, Size); 


DosSubSet 


DosSubSet has two options: initialize a memory block before it is suballocated 
via DosSubAlloc, or increase the size of an already suballocated memory block. 
The size of a suballocated block cannot be decreased. ‘The maximum size to which 
a suballocated block can be increased is limited by the declared size of the orginal 
pre-allocated block minus 8 bytes. This, of course, depends on whether the 
original block has been partitioned into any other suballocated blocks. If there 
have been many concurrent suballocation requests, the programmer must keep 
track of the memory usage. 

To increase a suballocated block beyond the size of the original block, the 
process needs to use DosReAllocSeg to change the size of the original memory 
block, then DosSubSet to increase the size of the suballocated block. To decrease 
the size of a suballocated block, the programmer allocates a smaller block using 
DosAllocSeg or DosSubAlloc, copies the data into the smaller block, and then 
deallocates the larger original suballocated block. 

DosSubSet expects three parameters: the orginal segment selector (which was 
returned by DosAllocSeg or DosAllocShrSeg), the option flag, and the new size to 
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which the suballocated block will be changed. The option flag specifies the 
function to be performed by DosSubSet, either to initialize a memory block or to 
change the size of an already suballocated memory block. When the initialized 
option is specified, the entire memory block as it was preallocated by DosAllocSeg 
is initialized and the size parameter ignored. The size parameter is used only to 
indicate the new size for the size increase option. 


DosSubSet (SegSelector, Flag, Size) 


unsigned SegSelector; /* selector of segment where memory 
will be suballocated */ 
unsigned Flag; /* specify the type of function to be 


performed */ 


unsigned Size; /* new size of the suballocated memory 
block */ 
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Example 


}tdefine INITIALIZE 0 
ttdefine RESIZE 1 


unsigned Selector; 
unsigned BlockOffset; 
unsigned Size; 


unsigned flag; 


ehar tar *p; 


DOSALLOCSEG((S2 *ig24). f= 30K -*7 
(unsigned far *)&Selector, 
O)s 


DOSSUBSET (Selector, INITIALIZE, 0): 


pige = 10 * 1024; 
DOSSUBALLOC (Selector, (unsigned far *) &BlockOffset, 


Size) /* suballocate 10K of memory */ 
FP_SEG(p) = Belecter; /* gat wp p to point to euballocated 
FP_OFF(p) = BlockOffset; /* memory block */ 
Sige = 12 * 1024; /* new size */ 


DOSSUBSET (Selector, RESIZE, sige): 


Shared Memory Functions 


Under OS/2 the same memory segments can be shared among different 
processes simultanenously. This capability is usually referred to as shared memory. 
The most important usage of shared memory is interprocess data sharing and data 
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transfer. Data can be transferred between processes when it is copied to a shared 
memory location by one process and then read by another process. Shared 
memory is very flexible. Data can be transferred among any number of cooperat- 
ing processes, whereas a pipe or queue allows only one receiving process. And, 
since memory manipulation is the fastest I/O operation, shared memory requires 
very little system overhead. 

Data can be shared when shared memory is allocated for use by more than one 
process. Variables or arrays can be stored on a shared allocated memory block and 
all the processes with access to this block can read and manipulate their values. 
When memory is shared and manipulated by multiple processes, it is necessary to 
establish mutual exclusion to ensure that the values of the shared memory 
variables are in a consistent state. 

There are two methods for establishing shared memory. The first method 
requires one process to declare a shared memory segment with a preestablished 
name using the function DosAllocShrSeg. Other processes can access the shared 
segment by issuing DosGetShrSeg with the same name. 

The second method involves DosAllocSeg/DosAllocHuge and DosGiveSeg or 
DosGetSeg. One process must allocate the memory segment using DosAllocSeg/ 
DosAllocHuge. Recall from page 175, that when a memory block is allocated using 
DosAllocSeg, bit 0 and bit 1 of the parameter Allocklag specify whether the block 
can be shared via functions DosGiveSeg and DosGetSeg, respectively. If bit 0 is set 
(equal to one), the memory block can be shared using DosGiveSeg. If bit 1 1s set, 
the block is shareable via DosGetSeg. 

When a process issues DosAllocSeg to allocate a memory block, that process 1s 
considered the owner of the memory block. The owner process can use DosGi- 
veSeg to give another process access to this memory block. The block is also 
accessible to another process that uses DosGetSeg. The difference between these 
two functions is that DosGiveSeg must be issued by the process that owns the 
memory block, while DosGetSeg is issued by the process that wants to access the 
block. 


Considerations for Using Shared Memory for Data Transfer 


Establishing data transfer with shared memory presents severe disadvantages 
and difficulties in coordination between the sending and receiving processes. 

When data is sent by one or multiple processes and read by others, there is no 
built-in provision that determines whether the receiving processes have actually 
read the data. Imagine this scenario: process 1 copies data to a shared memory 
location. Process 2 is supposed to read the data placed at the same location. 
Process 1 has no way of knowing whether process 2 has read the data. Therefore, 
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process | might overwrite the old data with new information even though it has not 
been read yet. Because of this coordination problem, more than one process at a 
time should not send data to the same shared memory segment. Otherwise, the 
difficulties described in the above scenario will proliferate as several processes send 
data to the same location, and the data is overwritten by other sending processes. 

Some form of signalling must be established by the processes themselves to 
ensure that the data will not be accidentally overwritten by the sending processes. 
Mutual exclusion must be established when several processes have the capability 
of changing the values of the shared memory block to ensure that the data remains 
in a consistent state. 

Both of these necessities demand extra overhead from an application and extra 
coding by the programmer. Shared memory, therefore, is only recommended for 
data transfer situations where the transfer will only take place once. It is suitable 
when data such as file handles, queue handles, or pipe handles need to be sent 
between processes. These values remain constant. Once they are read, the sending 
process does not need to resend them. 

Shared memory should not be used when the sending process needs to send 
data in a continuous stream, especially in cases where the sequence of the received 
data is crucial. If two processes, process 1 and 2, need to send data received from 
the asynchronous port to process 3, it is better to use a pipe than shared memory. 
Then the sending and receiving processes do not need to be concerned with 
synchronization or the integrity of the data. If you implement this form of data 
transfer using shared memory, your application must implement a synchroniza- 
tion mechanism between the sending and receiving processes to insure that the 
data is not overwritten before itis read. This problem is that of protecting an SRR. 


Sharing Memory using DosAllocShrSeg 


To set up a shared memory block, one process must allocate the block using the 
function DosAllocShrSeg. DosAllocShrSeg requires that the shared memory 
block be assigned a name. Using this name, another process accesses the shared 
memory block via DosGetShrSeg. The name of the shared memory block must 
have the format: 


\ SHAREMEM\name 


just as if it was a file called, name, located on the directory\SHAREMEM\. There’s 
no need for the directory \ SHAREMEM\ to exist on the disk and no file is created 
on the disk either. The shared memory block name is kept by OS/2 in an internal 
buffer. An example of a shared memory block name is: 
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\ SHARENAME\TEST .MEM 


The process that creates the shared block automatically has access to the 
segment. Other processes must obtain access to the shared block using Dos- 
GetShrSeg. But before a process can access a shared memory segment, it must first 
be given the name of the shared block. This can be done either by giving the 
memory segment a name that has been previously agreed upon, or by having the 
allocating process pass the name to the target process with other methods of IPC. 
If the name is predefined, the process that wishes to gain access to the shared 
memory segment simply specifies the predefined name as a parameter of Dos- 
GetShrSeg. 

Once the block is allocated or accessed by DosAllocShrSeg or DosGetShrSeg 
respectively, OS/2 returns the selector of the memory block. Using the selector, 
the processes can address memory locations on the block. The selector of the 
memory block is also required by other memory functions. Once the process no 
longer needs the shared memory block, it should return the memory block to OS/ 
2 using DosFreeSeg (discussed earlier in this chapter). 


DosAllocShrSeg 


DosAllocShrSeg allocates a shared memory block to the calling process. Three 
parameters must be specified: the size of the memory block, the pointer to an 
ASCIIZ string indicating the name of the shared memory block, and a pointer to 
a 2-byte (WORD) or an unsigned variable where OS/2 returns the value of the 
selector of the memory block. The largest size memory block that can be allocated 
is 65,535 bytes (64K). If the size value is 0, the default size of 65,535 bytes is assumed 
by OS/2. 

DosAllocShrSeg works with DosGetShrSeg to set up a shared memory block 
among multiple processes. When several processes need a shared memory block, 
one process must use DosAllocShrSeg to allocate it. Once allocated, the block is 
assigned a name; the other processes obtain access to it by specifying the same 
name when using DosGetShrSeg. 

Once the allocating process no longer needs the shared memory block, it 
should release it to OS/2 using function DosFreeSeg (covered earlier in the 
chapter). Other processes can continue to use this memory segment even after it 
is freed and the allocating process has terminated. OS/2 only returns a shared 
memory block into the system memory when there are no other processes with 
access to the block. For this reason, every process which accesses a shared memory 
segment with DosGetShrSeg must also issue DosFreeSeg when it is finished. Every 
time a process obtains access or releases a shared memory block, OS/2 increases 
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or decreases the value of an internal reference count which indicates the number 
of processes currently using the memory block. After the last process using the 
shared block frees it with DosFreeSeg the count reaches 0 and OS/2 returns the 
block to the free memory pool. 

OS/2 only allows 30 shared memory blocks to be allocated by one process at the 
same time using DosAllocShrSeg. If an application needs more than 30 shared 
memory blocks at a time, there is another API function which can be used to 
allocate shared memory: DosAllocSeg. 


DosAllocShrSeg (Size, Name, Selector) 


unsigned Size; /* size of block in number of bytes */ 


char far *Name; /* ASCIIZ string specifying the name of 
the block */ 


unsigned far *Selector; /* pointer to the selector of the memory 
block to be returned by OS/2 */ 
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DosGetShrSeg 


DosGetShrSeg accesses an already-allocated shared memory block for the 
process that issues it. The shared memory block must be allocated by another 
process with the function DosAllocShrSeg, which requires that a name be assigned 
to the block. To access the already-allocated shared memory block, the name of 
that particular memory block must also be passed to DosGetShrSeg. This name is 
obtained by the process through prior agreement toa predefined name or by some 
form of IPC. DosGetShrSeg also returns the selector of the shared memory block. 

Each time a process accesses the shared memory block, OS/2 increments an 
internal reference count which indicates the number of processes currently using 
this particular shared memory block. When the process no longer needs the 
shared memory block, it releases it using the function DosFreeSeg (covered 
earlier). OS/2 then decrements the reference count. When the reference count 
of a shared memory block reaches 0 after DosFreeSeg is issued, OS/2 returns the 
shared memory block to the system memory. 


DosGetShrSeg (Name, Selector) 


char far *Name; /* ASCIIZ string specifying the name of 
the block */ 


unsigned far “Selector; /* pointer to the selector of the memory 
block to be returned by OS/2 */ 
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Examples 


/* SHARE .H 
This file defines the shared segment name which both 
programs must use in order to share the memory segment. 


a | 
+#define 


/* thie 
this 


+#define 
+tdefine 


+#define 
+#define 


SHRSEGNAME “\ SHAREMEM \ SHARESEG. MEM” 


is a useful macro to convert a selector into a pointer 
macros is simply a combination of FP_SEG and FP_OFF */ 


GETSEGPTR(selector, off) ((char far *) (( (long) 
selector<< 16) + off)) 


WAITFOREVER a /* parameters for DOSSEMREQUEST */ 
NOWAIT 0 
NULL 0 


struct ShareData { 
long semaphorel; 
long semaphore?2; 


rs 
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/* SHARE.C 
PARENT: NONE 
CHILD: CHILD.C 


This program demonstrates: 


how several processes can share memory segments using 
DosAllocShrSeg and DosGetShrSeg. 


how to implement RAM semaphores to protect an SRR between 
two processes. 


SHARE.EXE simply use DOSSEMREQUEST to set a semaphore, 
then goto sleep for 5 seconds. 


SHRCHILD.EXE waits for the semaphore while displaying some 
characters on the screen, until the semaphore is clear. 


Notes: 
The parent process use DosAllocShrSeg to creates the 
shared segment. Starts the child process which then uses 
DosGetShrSeg to obtain access to the shared segment. 


Both programs must know in advance the shared memory 


segment name. We simply make this a constant. The name 
can be passed as an argument when the child process is 
Spawned. 


a 

fHinclude <doscalls.h> 

fFinclude <dos.h> 

#Hinclude <subcalls.h> 

fHinclude “share.h” /* common declarations between processes */ 
char ShrSegName[] = SHRSEGNAME; 

char PgmName[] = “CHILD.EXE”; /* child program name */ 


main() 


{ 
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unsigned ret; 
char far “pir; 
struct ShareData far *SemPtr; 


unsigned selector; /* use for DosAllocShrsSesg */ 


struct ResultCodes ReturnCodes:/* return code structure */ 
/* there is no sanvironment buffer */ 


/* allocate the shared memory segment */ 


ret = DOSALLOCSHRSEG(sizeof(struct ShareData), /* segment 


gize */ 
(char far *) ShrSegName, /* share seg name */ 
(unsigned far *)&selector); _ #* gelector */ 


printi(“\nShare: Shared Sesment esalector: %d “,eelector): 


if (ret) { 
printf (*\nAllocation of shared ses failed, error: 
%d”, ret); 
DOSEAIT(1, ©) 


FP SEG(SemPtr) = selector; 
FP OFF (SemPtr) ‘oF 


printf(*\nShare: Ftr te Shared Segment YFo”,SemPtr) : 
/* Thitialige the semaphore */ 

DOSSEMCLEAR ((long)&SemPtr->semaphorel) ; 
printf(“\nShare: Clear Ram Semaphore”) ; 


/* spawn the child process */ 


ret = DOSEXECPGM( (char far *)NULL, /* ObjNameBuf */ 


(unsigned) 0, /* ObjNameLen */ 
(unsigned) 1, /* AsyneTraceFlags */ 
(thar tar *) NULL: /* Argument Ptr it | 
[Char far *)} Nii, /* Environment Pir */ 


/* ID & Termination Cedas */ 
(struct ResultCodes far *) GReturnCodes, 
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(char far *) PgmName ): /* child program name */ 


Le (ret) 4 
printi (“exec of child process failed,. arror: %d\n", 
ret); 
DOSEXIT(1, 0); 
/* we will only use Semaphore 1 */ 
/* gequest for semaphore */ 
printf(“\nSHARE set the semaphore “); 
DOSSEMREQUEST ( (long) &SemPtr->semaphorel, (long) 
WAITFOREVER) ; 
Heifer (" \ashARE sleeps *): 
DOSSLEEP(5000L); /* sleep for 5 seconds */ 
erinte(*\nSHARE cléare the semaphore *) ; 
DOSSEMCLEAR ((long)&SemPtr->semaphorel) ; 
DOSEXIT({ 1, 0 2; /* exit */ 
} 
}* CHILD. 
PARENT: SHARE. C 
CHILD: NONE 
i 
fHinclude <stdio.h> 
#finclude <doscalls.h> 
#fHinclude <subcalls.h> 
fHinclude “share.h” /* common declarations between processes */ 


char ShrSegName[] = SHRSEGNAME; 


main() 


{ 
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unsigned ret; 
struct SharedData tar *SemPtr: 


unsigned selector; /* use for DosAllocShrseg */ 

struct ResultCodes ReturnCedes:/* return code structure */ 
/* there is no environment buffer */ 

unsigned ExecFlags; /* @gecutioth tlace */ 


/* allocate the shared memory segment */ 
ret = DOSGETSHRSEG((char far *) ShrSegName, /* share seg 
name */ 


(unsigned far *)&selector) ; 
(* geleptor *7 


Lc (rec) 4 
printf (“\nObtaining shared seg failed, error: %d”, 
rer): 


DOSEXIT(1, QO): 
/* Get a far pointer from 4a 16 bit selector */ 
SemPtr = (struct ShareData far *) GEITSEGPIR(seléctor, 0): 


printf(“\n Child Waiting for Semaphore to clear”); 
while (1) { 


ret = DOSSEMREQUEST ((long) &SemPtr- 
>semaphorel, (long) NOWAIT) ; 


Lt (eet) 
prahtr(*." >): 
else 
break; 
} 
prince.” Va Child Process owned semaphore “); 


DOSSEMCLEAR ( (long) &SemPtr->semaphorel) ; 
DOSEXIT( 1, 0 }; /* exit */ 
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Shared Memory Using DosAllocSeg or DosAllocHuge 


A memory segment can be allocated for sharing using DosAllocSeg and 
DosAllocHuge by setting bit 0 or bit 1 of the parameter AllocFlag. Using 
DosGiveSeg, the creating process can give the shared segment to another process. 
The shared segment can also be obtained by another process using DosGetSeg. To 
manipulate the multiple-segments within the huge block, the other processes must 
also obtain the shift count via DosGetHugeShift as described in the section of that 
name earlier in the chapter. 


DosGiveSeg 


DosGiveSeg gives another process access to an already-allocated memory block. 
The single segment memory block must be allocated using DosAllocSeg with bit 
0 of the parameter AllocFlag equal to 1 (see the section on DosAllocSeg). If the 
memory block is a multiple segment, it must be allocated using DosAllocHuge with 
the share option specified, ShareInd equals 1. 

DosGiveSeg is not a straigtforward function. To understand its operation we 
need to take a look at how a selector is used. To address a memory block, either 
for obtaining values in the block or for changing these values, the selector of the 
block is required. When several processes use the same shared memory segment, 
the selectors of the shared memory segment are different in each process, even 
though the selectors point to the same memory segment (by pointing to identical 
descriptors in separate descriptor tables, see Chapter 19). Therefore, DosGiveSeg 
requires two parameters for two selectors. The first selector is that of the memory 
segment which the calling process wants to share. The other is a selector returned 
by OS/2 which will be used by the receiving process to access the memory block. 

The process which owns the memory block has to issue DosGiveSeg to give 
access to the block to another process. When DosGiveSeg is issued, OS/2 builds 
a descriptor for the shared block in the LDT of the receiving process (this is why 
the process ID of of the receiving process must be specified), and returns the 
selector for that descriptor. This selector is called the receiver selector. DosGiveSeg 
returns the receiver selector to be used by the receiving process; however, it does 
not return it to the receiving process, but rather to the calling one. The donor 
process then uses a method of interprocess communication to send the value of the 
selector to the receiving process. 

The list below summarizes the steps involved in allocating a shared segment 
using DosGiveSeg. 


Memory Management Concepts and Functions 209 


1. One process allocates the shared memory block using DosAllocSeg with bit 
0 of AllocFlags parameter equal to 1. This process is referred to as the 
owner process. 


2. The owner process issues DosGiveSeg to give access to the other process 
that requires access to the shared segment. The PID of the receiving 
process and the selector of the shared block is required. OS/2 returns the 
receiver's selector. 


3. The owner process sends the receiver’s selector to the target process that 
was specified by the PID (used in step 2) when DosGiveSeg was called. With 
the receiver selector, the target process can access the shared memory 
segment. 


DosGiveSeg expects three parameters: Selector, the selector of the memory 
block; PID, the process ID of the process that will receive access to the block; and 
Rec_Selector, a pointer to an address where the receiver selector is returned. 
Selector specifies the selector of the memory block which was returned by 
DosAllocSeg. Rec_Selector is a value returned by OS/2 which represents the 
selector of the receiving process. ‘The value of Rec_Selector has to be passed to the 
receiving process with any of the methods of interprocess communication de- 
scribed in Chapter 3. 


DosGiveSeg (Selector, PID, Rec_Selector) 


unsigned Selector; /* selector of the memory segment to be 
shared */ 

unsigned PID; /* process ID of the receiving process */ 

unsigned far *Rec_Selector; /* receiving process selector to be 


returned */ 
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Example 


/* GIVESEG.C 

PARENT: NONE 

CELL D GIVESEG2 . EXE 
This program demonstrates: 


how several processes can share memory segments using 
DosAllocSeg and DosGiveSeg. 


In this example, we will establish a pipe to send the 


receipient’s selector. The PID of the receiving process is 
known because it is a child process. Other methods of IPC can 
be used. 

Notes: 


In order to avoid confusion, whenever a shared memory 
variable is being altered by more than one process, it 
should be treated as an SRR. 


*y 
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include <doscalls.h> 
include <dos.h> 
include <subcalls.h> 


#fdefine NOTSHARED 0 /* shared flags for DosAllocSeg */ 
#fdefine SHAREGIVE 1 
ifdefine SHAREGET 2 
#fdefine NULL 0 
char PgmName[] = “GIVESEG2.EXE”; /* child program name */ 
char SemName[] = “\\SEM\\GIVESEG”; /* semaphore name */ 
main() 
( 

unsigned PipeSize; 

unsigned ret; 

unsigned ReadHandle, WriteHandle; /* read and Write 


handle for 
DosMakePipe */ 
unsigned BytesWritten; 


eHar far *p: /* pointer to memory segment */ 

/* this pointer must be far because it 
points to another segment other than 
the current segment pointed by DS */ 

unsigned selector; /* use for DosAllockes */ 


unsigned Rec_Selector; /* use for DosGiveSeg sf 

/* parameters for DosExecPam */ 
ehar arg|[40]; /* argument buffer */ 
Struct ResultCodes ReturnCodes:/* return code structure */ 


/* there is po environment buffer */ 


long SemHandle; /* parameter for DosCreateSem */ 
char temp[30]; 


printt(“\nCalling DosMakePipe “) ; 


PipeSize = 4096; /* pipe size is 4K */ 
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ret = DOSMAKEPIPE ((unsigned far *) &ReadHandle, 
(unsigned far *) &WriteHandle, 
PipeSize) ; 
af (ret) | 
printt(“\nError Creating Pipe, Errer Code 
ds", ret) 
DOSEXIT (0,0) ; 


/* eraate semaphore */ 


ret = DOSCREATESEM(1, /* non-exclusive ownership */ 
(long far *)&SemHandle, /* semaphore handle */ 
(char far *)SemName) ; /* semaphore name */ 

if Pet) | 
printf (“DosCreateSem failed, error: %x\n”, ret); 


DOSES IT (A. OF) 


/ 


/* putting the Read Handle in the argument string */ 


sprintf(temp,”%d %s”, /* put readhandle of pipe */ 
ReadHandle, /* and semaphore name in arg */ 
SemName) ; 

strepy(arg,PgmName) ; /* preparing argument string */ 


streat(argtstrlen(PgmName)+1,temp) ; 


DOSSEMSET (SemHand1e) ; 
/* spawn the child procees */ 


ret = DOSEXECPGM((char far *)NULL, /* ObjNameBuf */ 


(unsigned) 0, /* ObjNameLen */ 

(unsigned) 1, /* AgynoeTracerlase */ 
(ehar far *) ars; /* Argument Ptr oy 
(char far *) NULL, /* Environment Per */ 


/* ID & Termination Codes */ 
(struet ResultCodes far *) &ReturnCodes., 
(char far *) PgmName ); /* child prog name */ 


if (ret) { 
printf(“exec of child process failed, error: %d\n”, 
ret); 
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DOSEXIT(1L, O) 
} 
printf(“\nWaiting until child process is ready to 
receive”); 
DOSSEMWAIT(SemHandle, (long) -1); /* wait for chald 
process */ 


printf(“\nAllocating a 32K segment”) ; 
fret = DOSALLOGSEG( (32 * 1024), 
(unsigned far *)&selector, 
SHAREGIVE) ; /* segment will shareable */ 
/* and not discardable */ 
Lf (ret) 
printf(“\nDosAllocSeg failed, error code %d”, ret); 


printf(“\nDetermine the pointer to the segment”) ; 
FP_SEG(p) = selector; /* make long pointer to seg */ 
FP_OFF(p) = 0; 


oO] = *a’s /* modify the block content */ 
iL = “pes 

ole] = "as 

pls) = * ane; 


printf(“\nNew value of the memory block: %Fs”,p); 


/* At this point we want to issue DosGiveSeg to give 
the segment to the child process */ 


printf(“\nCalling DosGiveSeg”) ; 


ret = DOSGIVESEG (selector, /* galler selector */ 
ReturnCodes.TermCode_PID, /* PID of receiving 
process* / 
(unsigned far *)&Rec_Selector) ; /* rvecepient’s 


selector */ 
if (cat) { 


printt (“DosGiveses failed, error: %d\n". ret): 
DOSEAIT CL, OF 


DOSSEMSET(SemHandle) ; 
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printf(*\nWrite receipient’s selector to pipe “): 
DOSWRITE (WriteHandle, /* write to the pipe */ 
(ehar far *)GRec Selector, /* Recepient selector */ 
sizeof(Rec_Selector), 
&BytesWritten) ; 

DOSSEMWAIT(SemHandle, (long) -1); /* wait until the 
semaphore is clear by 
the child process */ 

printf(“\nChild process has received segment”); 

printf(“\nNew value of the memory block: %Fs”,p):;: 

eo) = a4 /* modify the block content */ 

oil] = 

Sie) = hes 

p[3] “os 

ret = DOSFREESEG(selector) ; 

if (ret) 

printfi(“\nError dealloecating segment: %d”, ret); 
DOBEAIT (14.0 }s /* esi *s 
} 
/* GIVESEG2.C 
PARENT: GIVESEG. EXE 
2) MIE. NONE 


This program demonstrates how to receive a shared memory segment 
using DosGiveSeg. 


The receiving process simply reads the selector from the pipe. 


include <stdio.h> 
include <doscalls.h> 
Finclude <dos.h> 
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main(argc,argv) 
Lit argc; 
enar *arey||: 


int ReadHandle; /* Pipe Read Handle */ 


unsigned ret; /* sehen code */ 
unsigned i; 


/* uge for DosOpensSem */ 
char SemName [30]; /* semaphore name */ 
long SemHandle; 


unsigned BytesRead; /* use for DosRead */ 

ehar tar “p: /* pointer to memory block */ 
unsigned Rec_Selector; /* tecepiéent’s selector */ 
orante |" \n Entering GIVESEG2 Process “); 


ft (aree < 3) 4 
prince? a Pipe Read Handle and Semaphore name 
Hissing”); 
DOSEXIT(O.,.0) ; 


sscanf(argv[1],”%d”, &ReadHandle) ; 

sscanf(argv[2],”%s”,SemName) ; 

printr (A Read Handle: <%d> Semaphore: <%s>”, 
ReadHandle, SemName) ; 


printt (in Open Semaphore”) ; 


ret = DOSOPENSEM( (long far *)&SemHandle, /* open 
sempahore */ 
(char far *)SemName) ; 


if (ret) { 
printf(“\nDosOpenSem failed, Error Code <%d>”,ret) ; 
DOBEXIT( 1.0) 3 
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DOSSEMCLEAR(SemHandle); /* clear the semaphore to 
notify that the child 
process is ready to receive */ 


PFintt ("in Read the pipe”); 

ret = DOSREAD (ReadHandle., 
(ehar far *)&Rec Selertor, 
sizeot (Rec Selector), 
&BytesRead) ; 


if (fet) 4 
printf(“\nError Reading Data from Pipe, Error Code 
Cha?” , ret) + 
DOSEXIT(1,0)% 


primer (*\sa Selector Receive: %d”,Rec_Selector) ; 


print? (? i Determine the pointer to the segment”) ; 


FP_SEG(p) = Ree_Selector; /* make long pointer to seg */ 
FP ORE (5). = Gs 


printi(* \n Value of the memory block: %Fs”,p); 


o[G)] = *A’; /* modify the block content */ 
pLli = "as 
ol2) = *C 


ret = DOSFREESEG(Rec_Selector) ; 
if | eee) 

erinct (* vn Error deallocating segment”) ; 
DOSSEMCLEAR(SemHandle) ; 


DOSEXIT(1,0): /* terminate */ 
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DosGetSeg 


DosGetSeg allows a process to access a block of memory previously allocated by 
another process. The shared memory block must be allocated using DosAllocSeg 
or DosAllocHuge, with bit 1 of the parameter AllocKlags equal to 1. 

To access to a memory block via DosGetSeg, the calling process must have the 
selector of the memory block returned by DosAllocSeg or DosAllocHuge. Since 
the process that issues DosGetSeg does not allocate the memory block, it must 
obtain the selector from the process which allocated the memory block or the 
owner process. Therefore, the owner process has to send the value of the selector 
to every other process that wishes to access the shared memory segment. The 
following list summarizes the steps required in allocating shared memory using 
DosGetSeg. 


1. One process allocates the shared memory block using DosAllocSeg or 
DosAllocHuge with bit 1 of AllocFlags parameter equal to one. This 
process is referred as the owner process. 


2. ‘The owner process sends the selector of the shared block to all processes 
that need to access the shared block by any method of IPC. 


3. Once a selector is obtained, the other process uses DosGetSeg with the 
selector to obtain access to the shared memory block. 


If DosGetSeg is successful, the calling process can address the shared memory 
block using the value of the selector. If DosGetSeg was not issued, any attempt to 
address the block using the selector value will generate an error. 


DosGetSeg(Selector) 


unsigned Selector; /* selector of the memory segment to be 
shared */ 
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Example 

ae GETSEG.C 

PARENT: NONE 

CHILD: GETSEG2 . EXE 


This program demonstrates: 


how several processes can share memory segments using 
function DosAllocSeg and DosGetSeg. 


In this example, we will establish a pipe to send the 
selector. Other methods of IPC can be used. 


Notes: 
In order to avoid confusion, whenever a shared memory 
variable is being altered by more than one process, it 
should be treated as an SRR. 

mf 

include <doscalls.h> 


include <dos.h> 
include <subcalls.h> 


define NOTSHARED 0 /* shafted flaps for DosAllocSes */ 
}tdefine SHAREGIVE 1 

define SHAREGET 2 

#tdefine NULL 0 

char PgemName|] = “GETSEG2.EXE” ; /* child program name */ 
char SemName[] = “\SEM\GETSEG” ; /* semaphore name */ 


main () 

{ 
unsigned PipeSize; 
unsigned ret; 
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unsigned ReadHandle, WriteHandle; /* read and Write 
handle for 
DosMakePipe */ 
unsigned BytesWritten; 


char far *p; /* pointer to memory segment */ 

/* this pointer must be far because 
it points to another segment other 
than the current segment pointed 
by DS #7 

unsigned selector:/* use for DosAllocSeg */ 


/* parameters for DosExecPgm */ 
ehar are [40]; /* argument buffer */ 
Strict ResultCodes ReturnCodes:/* return code structure */ 
/* there is no environment buffer */ 


long SemHandle; /* parameter for DosCreateSem */ 
char temp [30] ; 


printf(“\nCalling DosMakePipe “); 


PipeSize = 4096; /* pipe size is 4K */ 
ret = DOSMAKEPIPE ((unsigned far *) &ReadHandle, 
(unsigned far *) &WriteHandle, 
PipeSize) ; 
if (ret) { 
orintt (“\nError Creating Pipe, Error Code 
<¥%d >” , ret) ; 
DOSEXIT(O,0)3 


/* create semaphore */ 


ret = DOSCREATESEM(1, /* non-exclusive ownership */ 
(long far *)&SemHandle, /* semaphore handle */ 
(char far *)SemName) ; /* semaphore name */ 

tf [eety 4 
nrintt(*DosCreatesem failed, error: Yx\n". ret): 


DOSEXIT(1, QO): 
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/* putting the Read Handle in the argument string */ 


sprintf(temp,”"%d %s”, /* out readhandle of pipe */ 
ReadHandle, /* and semaphore name in arg */ 
SemName) ; 

strepy (arg, PgmName) ; /* preparing argument string */ 


streat(argtstrilen(PgmName)t+1,temp) ; 


/* epawt the child process */ 


ret = DOSEXECPGM((char far *)NULL, /* ObjNameBuf */ 


(unsigned) 0, /* ObjNameLen */ 

(unsigned) 1, /* AsyneTraceFlage */ 
(char far *) are, /* Argument Ptr a | 
(char fer *) NULL. /* Environment Ptr */ 


/* 10 & Termination Godes */ 
(struct ResultCodes far *) &ReturnCodes, 
(char far *) PomNeme ); /* child prosream name */ 


tf (ret) | 
printt (“exec of child process fadled,. arror: %d\n”, 
ret); 
DOSEXIT(1, 0); 
} 
printt(“\nWaiting until child process is ready 
| to receive”); 
DOSSEMSETWAIT (SemHandle, (long) =<1): /* wait for child 
process */ 


printf(“\nAllocating a 32K segment”) ; 
ret = DOSALLOCSEG((32 * 1024), 
(unsigned far *)&selector, 
SHAREGET) ; /* seement will shareable */ 
/* and not discardable */ 
if (ret) 
printf(“\nDosAllocSeg failed, error code %d 


99 


ret) : 


printf(“\nDetermine the pointer to the segment”) ; 
FP_SEG(p) = selector; /* make lone pointer to seg */ 
FP OFF ior = 0,5 
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p[0] ‘a’; /* modify the-block content */ 
oli) = *Bs 

ele) = es 

p[3] = ‘\0’: 


printf(“\nNew value of the memory block: %Fs”,p); 


orintt(“\nWrite receipient’s selector to pipe “); 


DOSWRITE(WriteHandle, /* Vette LO the pipe “7 
(ehar far *)é&selector, f* Recepient selector */ 
sizeof(selector), 

&BytesWritten) ; 


DOSSEMSETWAIT(SemHandle, (long) -1); /* wait until the 
semaphore is clear 
by the child 
process */ 


printf(*\nChild process has received segment”): 
printf(“\nNew value of the memory block: %Fs”,p); 
if {ret) { 
Prints (* yn DosFreeSeg failed, Error Code 
Cod2", rat): 
DOSEXZIT (1.0) 


DOSEXIT( 1, 0 3): j* exit */ 
} 
/* GETSEG2 .C 
PARENT: GETSEG.EXE 
CHILD: NONE 


This program demonstrates how to receive a shared memory segment 
using DosGetSeg. 


The receiving process simply reads the selector from the pipe. 


*} 
include <stdio.h> 
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include <doscalls.h> 
include <dos.h> 


main(argc,argv) 
Lit, arac; 
hac *arey ||: 


{ 


int ReadHandle; j/* Pipe Read Handle */ 
/* other data */ 
unsigned ret; /* veturn code */ 


unsigned i; 


/* use for DosOpenSem */ 
char SemName [30]: /* semaphore name */ 
long SemHandle; 


unsigned BytesRead; /* se for DesgRaad */ 

cher Par tp; /* peinter to memory block */ 
unsigned selector; /* recepient’s selector */ 
orintt ("\n Enterins CETSEG2 Precess *): 


if (aroe < 3) 4 
erante (*\n Pipe Read Handle and Semaphore 
name missing”); 
DOSEXIT(0,0) ; 


sscanf(argvl1],”%d”,&ReadHandle) ; 

sscanf(argv[2],”%s”,SemName) ; 

prantt (* \A Read Handle: <%d> Semaphore: <%s>”, 
ReadHandle, SemName) ; 


eraier (°° Open Semaphore”); 
ret = DOSOPENSEM( (long far *)&SemHandle, /* open 
sanpahore */ 


(char far *)SemName): 


Le Lreet. 4 
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printf(“\nDosOpenSem failed, Error Code <%d>”, ret); 
DOSEXIT (1,0) : 


DOSSEMCLEAR(SemHandle); /* clear the semaphore to notify 
that the child process is ready 
to receive */ 


printf (“\n Read the pipe”); 
ret = DOSREAD (ReadHandle, 
(ehar far *)&selector, 
sizeot(selector), 
&BytesRead) ; 


if (ret) { 
printf(“\nError Reading Data from Pipe, Error Code 
Cid?" , ret): 
DOSEXIT (1.0) 
} 


printr(*\n Selector Receive: %d”,selector); 


ret. = DOSGETSEG(selector) ; 
Lf (eet) | 
erintr lin DosGetSeg failed, Error Code 
Rade”, Cet) * 
DOSEXIT (1,0) : 
} 


precy 6% Determine the pointer to the segment”) ; 
FP_SEG(p) = selector: /* make long pointer to seg */ 

FR OFF(p) = 0; 

etinir ("Hi Value of the memory block: %Fs”.,p); 
p[O] = ‘A’: /* modify the block content */ 
pili HBr 

Biol = “eC! 


ret = DOSFREESEG(selector): 
if (ret) { 
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Orin (A DosFreeSeg failed, Error Code 
<a?" , Pet): 
DOSEXIT(1,0); 
} 
DOSSEMCLEAR(SemHandle) ; 


DOSEXIT(1,0) % /* terminate */ 


Chapter 5 





Queue 


ueue is a system resource designed as a solution for data transfer problems 
that require a more complex and flexible method than the pipe. Under 
OS/2, queue is implemented using shared memory, which means that as 
a method of data transfer, queue possesses many of the same strengths and 
weaknesses as shared memory. In a sense, queue acts under OS/2 like a shared 
memory manager. It eliminates the need for applications to do much of the 
bookkeeping associated with using shared memory for interprocess data transfer. 
Unfortunately, the designers of queue did not eliminate enough progammer 
overhead when using queue for complex interprocess data transfer. In the final 
analysis, the implementation of queue under OS/2 suffers from shortcomings 
which limit its potential for anything other than fairly straightforward applications. 


Features of Queue 


In data structure terminology, queue is a FIFO (first-in-first-out) list (or data 
stream) where the data is inserted at one end and taken out at the other. An 
example is that ofa line, say, of people waiting to get into a trendy Manhattan club. 
Each person waiting on line is analogous to a data element on the queue. Ina FIFO 
queue, a person who wants to get into the club must go to the end of the line. The 
first person on line gets into the club first, just as the first element of a queue is read 
first. In the strict definition of a queue, there is no “cutting in line.” 

Queue as implemented by OS/2 differs from this strict definition in that data 
can be read from it not only in FIFO order but also in LIFO (last-in-first-out, a 
property of a data structure called a stack) order and also in a priority order 
specified by the application. The latter possibility is the equivalent of letting certain 
data elements, perhaps celebrities, cut into the line. The OS/2 queue is different 
from a strict mathematical definition of a queue; these differences, however, 
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provide the application with a much more flexible tool for data transfer. 
The following is a list of features of queue as implemented under OS/2: 


= Multiple processes can send data to a queue, but, like pipe, only one 
process can read from it. 


= The queue is specified by a queue handle returned by OS/2. 


= 'l’he data elements in a queue can be arranged in a FIFO order, LIFO order, 
or in a priority order specified by the application. 


" Unlike pipe, where the data is sent as a stream of bytes, the data in queue 
is separated into distinct data elements. Data is sent and received one data 
element at a time. If one process sends 5K of data, this block of data is 
treated as a data element 5K bytes long. Once received, the data element 
is read as a 5K block of data. The receiving process has no control over the 
size of data that it wants to read; the size is controlled by the sending 
process. 


= Data elements are not kept in an OS/2 internal buffer but on shared 
memory segments accessible to all processes involved. OS/2 simply sends 
the selectors of the data element to the receiving process, thereby making 
the queue a very fast method of data transfer. 


= There is no size limit to queue except for the system virtual memory limit 
(in most cases the limit is the available disk space used for memory 
swapping) whereas pipe size is limited to 64K. The size of each data 
element could be larger than 64K. 


= The maximum number of queues that a system can handle at any one time 
is 409. ‘The maximum number of data elements that the system can handle 
is 3268 elements. This number reflects not the data elements per queue 
but the number of data elements for all the queues currently opened by the 
system. The two limits are related. For example, if you have four queues, 
there can be up to 3268 elements total, an average of 817 elements per 
queue. Even if you have 12 queues, they can can still only handle up to 3268 
elements, leaving about 272 elements per queue. 


= The optimal number of queues for each application is six, with a maximum 
total of 100 data elements for all queues opened by the application. 
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=" Data elements are not necessarily discarded once read by the receiving 
process, as in the pipe. The receiving process has full control over the 
removal of data elements from the queue. Thus, a data element can either 
be removed once it is read or be left on the queue. 


= The receiving process does not have to follow the previously specified data 
arrangement (FIFO, LIFO, or priority order) when reading data elements 
on the queue. The receiving process has access to any data element stored 
on the queue. 


= Since queue is a separate system resource, separate functions are required 
to send and receive data from it. The queue handle cannot be used in 
conjunction with DosRead nor DosWrite for reading and writing to queue, 
though this is the case with pipe handles. 


Create, Open, and Close Queues 


A queue can have several sending processes but only one receiving process. 
Using DosCreateQueue, the receiving process creates the queue. Once created, 
the queue can be opened by the sending processes using DosOpenQueue. The 
arrangement of the data elements and the queue name have to be known by both 
the sending and receiving processes before the queue can be used. Once the 
queue is no longer needed by a process, it should be closed using DosCloseQueue. 

A queue name is defined as a pseudo file with a file name having the form: 


\QUEUE\queue_name. 


No file or directory “\QUEUE” actually exists on the disk drive. This is because 
the data on the queue is kept in a special memory segment maintained by OS/2. 
The queue name specified by the process calling DosCreateQueue and the name 
specified by the reading processes calling DosOpenQueue must match exactly. 
The queue name can be agreed upon beforehand, or exported to each receiving 
process using other forms of interprocess communication such as the arguments 
of DosExecPgm, shared memory, or a pipe. 

The arrangement of the data elements must be specified by the process that 
creates the queue using DosCreateQueue. There are three possible orders of 
arrangement: FIFO, LIFO, or priority order. In a FIFO order, the first data 
element sent is the first element to be read on the queue. In LIFO order, the last 
data element sent is the first element to be read on the queue. LIFO order is 
similiar to going through a stack of books. The last book put on the stack will be 
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the first removed. The first book to be put on the stack will always be the last one 
removed. When the queue is arranged in a priority order, each data element is 
assigned a priority number. The data element with the highest priority is the first 
element available off the queue. | 

Once the queue is created by DosCreateQueue or opened by DosOpenQueue, 
OS/2 returns a queue handle to the calling process. The queue handle is a 
required parameter for other queue functions. 


| DosCreateQueue 


Before other processes can send data to the queue, the queue has to be created 
by the receiving process using DosCreateQueue. The creating process is consid- 
ered the owner of the queue. Only the owner can read or remove the data elements 
from the queue. It is identified by the name given to it: DosCreateQueue. Any 
other process that has been given the same name can open the queue (using Dos- 
OpenQueue) and send data to it. 

A queue can be closed using the DosCloseQueue function. OS/2 maintains the 
queue’s resource as long as the owning process does not close the queue. Other 
sending processes should close the queue once they are finished using it, but 
OS/2 will not delete the queue until the owner process closes it. Because of this, 
the programmer should make sure that the queue is not used by any sending 
process when the queue is closed by the receiving process. 

Once a queue is created, a queue handle is returned by function DosCreate- 
Queue. The queue handle is used to retrieve data from the queue using DosRead- 
Queue or DosQueryQueue and other queue functions. All of the owner process’s 
child processes inherit the queue handle, but they will not be allowed to read or 
remove data from the queue, only write to it. 

DosCreateQueue expects three parameters: QueuePrty which specifies the 
arrangement order of the queue’s data element, the queue name, and an address 
to which the value of the queue handle is returned. The arrangement order can 
be FIFO, LIFO, or priority order. These orders were discussed in detail earlier. 


DosCreateQueue (QueueHandle, QueuePrty, QueueName) 


unsigned far *QueueHandle; /* address of the queue handle to bere- 
turned by OS/2 */ 
unsigned QueuePrty; /* specifies the order of the queue */ 


char far *QueueName; /* queue name */ 
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Compatability Mode Restriction 


No queue functions are available in real mode. 
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DosOpenQueue 


DosOpenQueue opens an existing queue for a sending process. Remember 
there can be any number of sending processes and one receiving process. The 
queue must have been created by another process (which is the owner and 
receiving process) before it can be opened by a sending process. Since OS/2 can 
maintain many queues, DosOpenQueue requires an identifying queue name. 
This queue name must be the same as the name used when the queue is created 
(via DosCreateQueue). A sending process, therefore, must obtain the queue 
name before issuing DosOpenQueue. It can do this by using a pre-defined name, 
or by any other method of IPC. 

Once a queue is created, a queue handle is returned by the DosOpenQueue 
function. The queue handle is used to send data elements to the queue using 
DosWriteQueue or for other queue functions. The queue handle is inherited by 
all child processes spawned by the process that opened the queue. The child 
processes will have the same writing access to the queue as the parent process. 
When the sending process no longer needs the queue, it should close the queue 
using DosCloseQueue. 

DosOpenQueue requires three parameters: QueueHandle, an address where the 
returned value of the queue handle is stored; OwnerPid, an address where the 
returned value of the queue owner’s process ID is stored; and the QueueName, 
which must be provided by the sending process. 


DosOpenQueue (OwnerPID, QueueHandle, QueueName) 


unsigned far *OwnerPID; /* address of the queue owner’s PID to 
be returned by OS/2 */ 
unsigned far *QueueHandle; /* address of the queue handle to be 


returned by OS/2 */ 


char far *QueueName; /* queue name */ 
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Compatability Mode Restriction 


No queue functions are available in real mode. 


DosCloseQueue 


DosCloseQueue closes the queue and prevents further attempts to access it. 
Once a process no longer needs the queue, it should close it. If the process issuing 
DosCloseQueue is a sending process, then it merely informs OS/2 that itis finished 
with the queue. (If it wishes to use the queue again, it will have to issue Dos- 
OpenQueue.) If the process is the owner of the queue, DosCloseQueue erases all 
elements currently available on the queue. Any sending process that currently has 
the queue open and tries to access it receives error 337, “Queue does not exist 
(invalid queue handle).” 


DosCloseQueue (QueueHandle) 


unsigned QueueHandle; /* the queue handle to be closed */ 
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Compatability Mode Restriction 


No queue functions are available in real mode. 


Sending and Receiving Data with Queue 


Data elements on a queue are kept in shared memory segments. Thus, each 
process involved in using the queue must have access to the shared memory 
segments. Any of the three methods for establishing shared memory segments 
between processes can be used. These are discussed in detail in Chapter 4. 

Data elements are read from the queue using the functions DosReadQueue or 
DosPeekQueue. For this reason, the receiving process must already have access to 
the shared memory segment where the data elements are stored. Both functions 
DosReadQueue and DosPeekQueue return an address or a pointer of the data 
element as well as the length of the dataelement. The difference is that once read, 
DosReadQueue removes the element from the queue, whereas DosPeekQueue 
does not. 

Any process involved in using the queue can find out the number of data 
elements on the queue using the function DosQueryQueue. Only the receiving 
process, or the process that creates the queue can erase all elements on the queue 
using the function DosPurgeQueue. 


Queue With Shared Memory 


The queue is a potentially useful and flexible solution to a wide range of com- 
plex interprocess data transfer applications. We emphasize “potential,” however, 
because of the way in which queue is implemented under the current version of 
OS/2. When using it for complex forms of interprocess data transfer, the 
application itself takes care of queue management. 

In a perfect queue, the synchronization mechanism between the sending and 
receiving processes would be transparent to the programmer. The sending 
process would just send data and the receiving process would just read it. However, 
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to use the OS/2 queue effectively a good deal of thought must be put into the 
design of the application. This is because the queue is instituted using shared 
memory, and many of the difficulties involved with using shared memory segments 
for interprocess data transfer also plague any implementation of the queue. 

We recommend that each data element placed on the queue be placed on an 
individual memory segment. This avoids the necessity of having to set up a 
synchronization mechanism to prevent locations on the memory segment from 
being written over before they are read (see the discussion in Chapter 4, “Using 
Shared Memory for Interprocess Data Tranfer”). However, this solution raises a 
new issue, that of the reclaimation of spent memory segments. Because OS/2 only 
recommends a maximum of 300 shared segments to be maintained by any process, 
the size of a queue will be limited to 300 elements unless a method is instituted to 
reclaim memory segments once they have been read from the queue. The queue 
resource provided by OS/2 does not include a mechanism that returns memory 
segments belonging to read data elements to the free memory pool. Nor does it 
provide a mechanism that informs a sending process that a data element has been 
read so that its memory segment can be reused to send another data element. The 
application itself must institute one of these methods of spent segment reclama- 
tion in order to implement a viable queue. 

Very complex methods can be developed to solve the memory reclamation 
problem. One is to set up an IPC mechanism between the receiving process and 
each sending process. Because DosReadQueue returns the PID of each sending 
process along with the data element, the receiving process can notify each sending 
process when a data element has been received by returning its selector. Each 
sending process maintains a list of the selectors of the data elements that it has sent 
on the queue. When it is informed by the receiving process that a queue element 
has been read it either issues DosFreeSeg to return the segment to free memory, 
or it reuses the segment to send aother queue element. This method works fine 
if DosGiveSeg is used to share queue segments since the sending process has a copy 
of the selector that is sent to the receiving process as well as the selector that 
returned by DosAllocSeg. However, if the receiving process uses DosGetSeg to get 
access to the data element segment, then the sending process does not have a copy 
of the selector returned by DosGetSeg. In this case some other protocol must be 
developed to allow the receiving process to tell a sending process which data 
element can safely be reclaimed. 

A more sophisticated solution to this problem involves setting up a separate 
process that acts as a queue manager. A queue manager process would normally 
be implemented as a dynamic link library. This method eleminates the need to set 
up a separate IPC channel for each sending process. Sending processes would 
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allocate memory and send data elements through the queue manager, and 
receiving processes would read the queue through it as well. Essentially, the queue 
manager would handle all the memory allocation for the queue. It would do this 
by maintaining a table containing all the selectors sent on the queue (one 
implementation would simply free the corresponding segment after a read 
request). The queue manager concept is very flexible, and the programmer can 
use it to implement a very sophisticated version of the queue, including providing 
for multiple receiving processes. Unfortunately, implementing a queue manager 
requires considerable programming effort, and amounts to replacing the OS/2 
queue utility with a new one. 

Fortunately, a viable queue (one that handles memory reclamation) can be 
implemented for multiple sending processes without the need for IPC mecha- 
nisms or a queue manager. This implementation takes advantage of the fact that 
OS/2 maintains an internal reference count for each memory segment shared 
with DosGiveSeg. When the sending process shares the segment it is sending on 
the queue with DosGiveSeg, it can immediately thereafter issue DosFreeSeg 
without deallocating the segment (without interfering with the reading proc- 
esses). Once the receiving process finishes with the segment, the segment is 
deallocated with DosFreeSeg. This method is simple (no IPC, no need for 
synchronization), elegant, and works with any number of sending processes. It can 
be used to efficiently implement the queue in almost all situations. However, if an 
application requires a large volume and high throughput queue, this method is 
insufficient. This is because OS/2 must build a new descriptor in the receiving 
process’s LDT every time there is a write request. In cases where high throughput 
is essential, a queue manager which recycles segments without deallocating them 
should be implemented. 


Queue Without Shared Memory 


A queue can also be implemented without any of the complexities of shared 
memory segments. The size of the data elements in this case, however, is limited 
to 2 bytes. The queue is implemented in the same way as a shared memory queue, 
except that the shared memory functions are omitted. As with a shared memory 
queue, the data elements are arranged in either FIF O, LIFO, or priority order. 
Data can be sent and received without any synchronization procedure. The 
receiving process can still selectively read and remove elements on the queue. The 
queue is able to hold up to 4000 2-byte data elements. These data elements are kept 
in an OS/2 internal memory buffer; there’s no need for ashared memory segment. 
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Recommended Method for Implementing Queue 


=" The receiving process creates the queue using DosCreateQueue. 
=" Fach sending process uses DosOpenQueue to access the queue. 


= Sending processes allocate shared data segments via DosAllocSeg (with the 
GIVESEG shareable flag ). Modify the contents of the segment accord- 
ingly. 

= Sending process use DosWriteQueue to send data element and immedi- 
ately deallocates the segment. 


= The receiving process uses DosReadQueue or DosPeekQueue to receive 
the element. The data address obtained from these functions is a double- 
word value. The high-word of the data address is the selector of the data 
segment. 


= The receiving process uses DosFreeSeg to deallocate the segment when it 
no longer needs the element. 


=" In order to safeguard against memory overrun, the data segment allocated 
via DosAllocSeg should only be used to contain the data element, and 
should be no larger than the data element. In other words, don’t use the 
shared data segment containing the queue data element for other pur- 
poses. 


= One possible constraint when using this method for IPC is the overhead 
involved in copying data to the shared data segment. For situations where 
a high transfer rate is required for a high volume of data, this overhead 
might slow down queue access. 


In order to prevent this, try to stay away from keeping two copies of the data 
element (one in the program’s memory and one in the shared data 
segment). If possible use the shared segment when generating the data for 
the data element. 


DosWriteQueue 


DosWriteQueue adds a data element to a queue. The data element on the 
queue has to be located on a shared memory segment accessible to the receiving 
process. The following parameters are required: a queue handle, a request data 
or an argument, the length of the data element, the pointer to the data buffer, and 
the priority of the data element. 
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The queue handle (specified by QueueHandle) is the value returned when 
the process opens the queue using function DosOpenQueue. 


The request data (specified by Request) is any value to be passed to the re- 
ceiving process along with the data element. This argument can be used 
as a signal, for event encoding, or as a special flag. The point is that OS/ 
2 does not care about the value of this parameter; it simply passes it to the 
receiving processs along with the data element. This parameter can be 
viewed as an appendage to the data element. The Request field can be used 
to send data on the queue without the data element. When this is done, 
there’s no need for a shared memory segment where the data element 
would normally be stored. 


A pointer to the data buffer (specified by DataBuffer) containing the data 
element must be passed to DosWriteQueue. The length of the data buffer 
(DataLength) in number of bytes must also be specified. The pointer is the 
starting address of the memory location where the data element is stored. 
This is a selector:offset combination. The data buffer of the data element 
must be stored on a shared memory segment. In cases where there’s no 
data element, the pointer is set to NULL and the data length is zero. 

The priority of the data element (specified by ElemPriority) is applicable 
when the queue is arranged in priority order. The priority is specified by 
a value from 0 to 15, with 15 being the highest priority. When the queue 
is arranged in a priority order, the highest priority element is at the head 

of the queue. When an element is added to the queue, if its priority is the lowest 
it will be putin the back of the queue and if its priority is the highest it will be placed 
in front. Elements with the same priority are arranged in FIFO order. 


DosWriteQueue (QueueHandle, Request, DataLength, DataBuffer, ElemPriority) 


unsigned QueueHandle; /* queue handle returned by 
DosOpenQueue */ 

unsigned Request; /* Request data or any argument */ 

unsigned DataLength; /* Length of the data element */ 

char far *DataBuffer; /* Pointer to the data buffer holding the 


data element */ 


unsigned ElemPriority; /* Priority of the data element */ 
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Compatability Mode Restriction 


No queue functions are available in real mode. 


DosReadQueue and DosPeekQueue 


DosReadQueue reads a data element, then takes the element off the queue. 
The data element must be stored in a shared memory segment which is accessible 
to the process. Only the process that created the queue is permitted to issue 
DosReadQueue to receive data from it. DosPeekQueue also reads a data element, 





238 Advanced Programmer's Guide to OS/2 


but the element is not taken off the queue. The two functions, DosReadQueue and 
DosPeekQueue, complement each other and allow the programmer flexbility in 
the manipulation of the queue. 

DosReadQueue and DosPeekQueue expect quite a few parameters. The next 
paragraphs explain them. Since both functions read data elements that have been 
added by DosWriteQueue, you should first learn how to use this latter function in 
order to understand more about these parameters. 

First, the queue handle of the queue (specified by QueueHandle) is a necessary 
parameter. The queue handle specifies the queue from which the data element 
will be read. [tis is the value returned when the queue is created using DosCreate- 
Queue. 

Request specifies a pointer to a data structure expected by both DosReadQueue 
and DosPeekQueue. Request comprises two WORDS or two unsigned variables 
with the following format: 


Struct RequestStruct { 
unsigned PID; 
unsinged RequestData; 


ts 


The first variable specified is the process ID (PID) of the sending process. The 
second variable is the request data which can be any value. The programmer 
determines the significance of the request data. To OS/2, this value has no signifi- 
cance; the value will automatically be sent along with the data element. 

When there is no shared memory, the RequestData parameter is used as the 2- 
byte data element. In this case, the buffer data address and the length of the data 
element are NULL and zero respectively. 

Third, the parameter DataLength is the address to which the length of the data 
element will be returned by OS/2. The length of the data buffer is in number of 
bytes. 

The fourth parameter, DataAddress, returns a pointer to the data element read 
from the queue. 

The fifth parameter is called ElementCode specifies the location of the data 
element to be read from the queue. Ifthe sixth elementis to be read, ElementCode 
is set to equal five (5). If ElementCode = 0, the first element is read. As mentioned 
earlier, if DosReadQueue is used, the data element is read and then taken off the 
queue. If DosPeekQueue is used, the data element is not removed from the queue. 

Both DosReadQueue and DosQueryQueue return the priority order of the data 
element read, at the address specified by ElemPriority, the sixth parameter. The 
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priority order is the value assigned to the data element by the sending process. If 
the queue is arranged in a priority order, the element with the highest priority 
order is placed in front of the queue. The range for the priority order is from 0 
to 15, with 15 being the highest priority. 

If no element is present in the position specified by the receiving process with 
ElementCode, the receiving thread has two options, either to wait until the 
element is put on the queue by a sending process or not wait at all. This option is 
specified by the NoWait parameter. If NoWait is equal to 0, the thread waits until 
the element is received. If the option NoWait is not equal to zero, the thread does 
not wait at all. 

The thread does not have to specify the wait option in order to receive a data 
element that is not currently on the queue. There is another parameter, 
SemHandle, which can be used to specify a semaphore handle. The semaphore is 
used with the no wait option. OS/2 clears the semaphore when the requested data 
element is put on the queue. This means that the thread does not have to wait to 
receive the data element; it can specify the no wait option, and continue its 
execution if the data element is not there. Later, the thread can determine 
whether the semaphore has been cleared or it can wait on the semaphore with any 
of the semaphore waiting functions discussed in Chapter 3. 


DosPeekQueue (QueueHandle, Request, DataLength, DataAddress, ElementCode, 
NoWait, ElemPriority, SemHandle) 


DosReadQueue (QueueHandle, Request, DataLength, DataAddress, ElementCode, 
NoWait, ElemPriority, SemHandle) 


unsigned QueueHandle; /* handle of queue returned by 
DosOpenQueue */ 

unsigned long far “Request; /* pointer to Request data structure */ 

unsigned far *DataLength; /* length of queue element */ 

unsigned long far *DataAddress; /* pointer to queue element address */ 

unsigned far ElementCode; /* position on queue of requested 
element */ 

char NoWait; /* wait option */ 

unsigned far *ElemPriority; /* priority level of returned element */ 


unsigned long SemHandle; /* semaphore handle */ 
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Compatability Mode Restriction 


No queue functions are available in real mode. 


DosQueryQueue 


DosQueryQueue returns the number of elements currently on the queue. Any 
process that has opened the queue can issue this function. An error “Queue does 
not exist (invalid QueueHandle), error number 337,” is returned if the queue was 
closed by the owner process. DosQueryQueue expects two parameters: the queue 
handle, and an address to store the value of the number of elements on the queue. 


DosQueryQueue(QueueHandle,NumberElements) 


unsigned QueueHandle; /* the handle of the queue that will be 
queried* / 
unsigned far *NumberElements; /* address to store the value of the 


number of elements of the queue */ 
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DosPurgeQueue 


DosPurgeQueue erases all elements on the queue. Only the owner process, the 
process that creates the queue using DosCreateQueue, can execute this function. 
This means that any thread belonging to the owner process can issue this function. 
DosPurgeQueue requires the queue handle of the queue to be purged. 


DosPurgeQueue (QueueHandle) 


unsigned QueueHandle; /* the handle of the queue that will be 
purged */ 





Examples 

/* QUEUE.H - Header file for Queue program */ 

+#define QUEUE_ NAME “\ \QUEUES\\TEST” 

+#define FIFO 0 /* definitions use for 
DosCreateQueue */ 

}tdefine LIFO 1 

}tdefine PRIORITY 2 

+#define NOWAIT 0 /* def. use for DosReadQueue */ 


ttdefine WAIT 1 
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#tdefine NEWPID 1 /* Operation. Sterus */ 
4tdefine EXIT 2 

ttKdefine DATA 0 

+#define READ 0 /* Read Status */ 


4Kdefine NOT READ 1 


typedef unsigned char BYTE: 
typedef unsigned short WORD; 
typedef unsigned long DWORD; 


#tdefine LOWORD(1) ((WORD) (1)) 

define HIWORD(1) ((WORD) (((DWORD) (1) >> 16) & OxFFFF) ) 
define LOBYTE(w) ((BYTE) (w)) 

#tdefine HIBYTE(w) (( (WORD) (w) >> 8) & Oxff) 


/* QUEUE; C 
PARENT PROCESS: NONE 
CHILD PROCESS: e268 


This program demonstrates how to implement queue under OS/2 
using DosAllocSeg, DosFreeSeg, DosGetSeg and queue API func- 
TLOUS . 


This program follows the algorithm described in the chapter. 

= receiving process creates the queue using DosCreateQueue. 

: sending processes use DosOpenQueue to access the queue. 

- sending process allocate a shared data segment via 
DosAllocSeg (with GIVESEG readable flag ). Modify the 


contents of the segment accordingly. 


: Sending process uses DosGiveSeg to send the data segment 
to the receiving process. 


2 sending process uses DosWriteQueue to send an element.Once 
sent, the segment is immediately deallocated via 
DosFreeSeg. 
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: Receiving process uses DosReadQueue or DosPeekQueue to 


read the element. The data address is a four-byte value 
and the high word of the value is the selector of the data 
segment. 


Receving process use DosFreeSeg to deallocate the segment 
when it no longer needs the elements. 


NOTES: 

: The two issues concerning queue in determining that all 
process involved in sending the data has stopped sending, 
and to determine whether a data segment is read or not. 
One can setup a pipe for this purpose. 

Another way is to use the Request Identification data for 
status purpose. There are two types of status 
informations. 

NEWPID 

eed a 
A new process that just open the queue, should use 
DosWriteQueue with Request = QStatus = NEWPID, with no 
data element attached. | 
This allows the receiving process to know that a process 
is about to send data. 
When the process no longer uses the queue, it should use 
DosWriteQueue with Request = Qstatus = EXIT, and no data 
element. This allows the receiving process to know that 
a sending process has just stopped sending data. 

oy 


include “stdio.h” 
Finclude “doscalls.h” 
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Fineclude “dos.h” 


fFinclude “queue.h” /* queue definition and data 


structure */ 


char QueueName[] = QUEUE_NAME; 
char PgmName[] = “Q2.EXE”; /* child program name */ 
main {) 


{ 


chat far “pir: 
unsigned Qstat; 


unsigned selector; /* ese for DosAllocShrSes */ 
struct ResultCodes ReturnCodes; /* return code 
striuctura */ 


/* there is no environment buffer */ 


unsigned QueueHandle; /* parameters for 
DosCreateQueue */ 


unsigned Elements; /* number of elements on queue */ 
long Request; /* parameters for DosReadQueue */ 
unsigned DataLength; /* length of element read */ 
long DataAddress; /* address of element read */ 


unsigned Selector; 


char BiemPriority 3 

unsigned QUsedCount = 0; /* number of processes 
currently using the 
queue */ 

unsigned Flag = 0; /* whether the queue 


has been opened by other 
process or not */ 
unsigned ret; 
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printf(“\nCreate the queue %s”,QueueName) ; 

cet = DOSCREATEQUEUE ((unsigned far *)&QueueHandle, 
ELPO, /* quéuae peierity */ 
(char far *)QueueName) ; 


if (ret) { 
printf(“\nDosCreateQueue failed: %d”,ret); 
DOSEXZIT(1,60); 


/* spawn the child proease */ 


praintt (“\seawn ehild orocess 1°“): 
ret = DOSEXECPGM((char far *)NULL, /* ObjNameBuf */ 


(unsigned) 0, /* ObjNameLen */ 

(unsigned) 1, /* AsyneTraceFlags */ 
(char far *)} NULL, /* Argument Ptr i 
(char far *) NULL, /* Environment Ptr */ 


/* ID & Termination Codes */ 
(struct ResultCodes far *) &ReturnCodes, 


(char far *) PgmName ); /* ehild prog. name */ 
if (ret) { 
printft(*\nexec of child process failed, error: 
a" Yet): 
DOSCLOSEQUEUE (QueueHandle) ; /* queue should be 
closed */ 


DOSEXIT(T, 0); 
} 


printf (“\nSpawn child process 2 “): 
ret = DOSEXECPGM((char far *)NULL, 
(unsigned) 0, 
(unsigned) 1, 
(char far *) NULL, 
(char far *) NULL, 
(struct ResultCodes far *) &ReturnCodes, 
(char far *) PgmName ); 
if (cat) { 
printf(“\nexec of child process failed, error: 
we”. Let) s 


while 
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DOSCLOSEQUEUE (QueueHand1e) ; /* queue should be 
closed */ 


DOSEXIT(1L. O)¢ 


con A 
/* determine the number of elements on queue */ 
Elements = 0; 
ret = DOSQUERYQUEUE (QueueHandle, 
(unsigned far *)&Elements) ; 
if (ret) { | 
printf(“\nDosQueuryQueue failed, %d”,ret); 
DOSCLOSEQUEUE (QueueHand1le) ; 
DOSEXIT(1; 0) 


/* the process that creates the */ 

/* queue, must be the one that */ 
reads data from i 

re ds data f Lt My 


if (Elements) { 
/* read data element */ 
ret = DOSREADQUEUE (QueueHandle, 
(long far *)&Request, 
(unsigned far *)&DataLength, 
(long far *)&DataAddress, 
0, /* element code, first element*/ 
NOWAIT, 
/* N/A - this is an FIFO queue */ 
(char far *)&ElemPriority, 
OL}; /* semaphore handle */ 
/* N/A - because of no wait 
option */ 
if (ret) { 
printf(“\nDosReadQueue failed %d”,ret); 
DOSEXTT (1,0) % 


Qstat = HIWORD(Request) ; 


if (DataLength = 0) { 
if (Qstat == NEWPID) { 
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printf(“\nAnother process has join 


us”); 
QUsedCountt+ ; 
Blae = 3 
} 
if (Qstat == EXIT. && Flag) { 
printf(“\nAnother process has left 
us” 
QUsedCount-; 
} 
} else { 
Selector = FP_SEG(DataAddress) ; 
if (ret) 4 
printf(“\nDosGetSeg failed, 
1a", Bet}? 


DOSEXIT(1,0): 


/* data element is read */ 

/* in this éxanple, we will only 
print the data element 
received */ 

ptr = (char far *)DataAddress; 
printf(“\nReceived Element: %Fs”,ptr): 
ret = DOSFREESEG(Selector); 
} 
if (Flag && QUsedCount == 0) /* no one using 
the queue */ 
break; 
} 


DOSCLOSEQUEUE (QueueHand1le) ; /* close the queue */ 
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f® O20 
PARENT PROCESS: QUEUE.C 
CHILD PROCESS: NONE 


This is the queue sending process. 
Please examine QUEUE.C for a more detail explaination. 
a 


include “dos.h” 
tinclude “doscalls.h” 


fHinclude “queue.h” /* queue definition and structure */ 
char QueueName[] = QUEUE_NAME; 
#tdefine NOTSHARED 0 /* shared flags for DosAllocSes */ 


hk 


4edefine SHAREGIVE 
4tKdefine SHAREGET 2 


define NULL 0 

tt}define BUFLEN 50 

void lstrepy(); 

youd letreastt) : 

unsigned lstrlen(); 

main () 

{ 
char far *p4 /* data element pointers */ 
Char far *s: 


unsigned QStat; 


unsigned Selector; 
unsigned RecSelector; 


unsigned OwnerPid; /* parameter for DosOpenQueue */ 
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unsigned QueueHandle; 
unsigned DataLength; 
struct Proc IDsArea ID; /* ProcID structure */ 


unsigned i, flag, ret; 
enar text [5] % 


/* open the queue */ 
ret = DOSOPENQUEUE ( 
(unsigned far *)&OwnerPid, 
(unsigned far *)&QueueHandle, 
(char far *)QueueName) ; 
Le (ret). 4 
printf(“\nDosOpenQueue failed %d”,ret):; 
DOSEXIT(1,0) 3 


QStat = NEWPID; /* tell the receiving proces of another 
sending process */ 
ret = DOSWRITEQUEUE (QueueHandle, 
(unsigned) QStat, 
0, /* no data is sant */ 
[char far *JNULL, 
O): /* alement priority N/A */ 
if (ret) { 
printf (“\nDosWriteQueue failed: %d”,ret): 
BDOSEXIT (1,0) 3 


ret = DOSGETPID((struct ProciDsArea far *)&ID): 
if (fet) -f 
printf(“\n DosGetPid failed: %d”,ret); 
ID, procid_cpid = 0; 


waite {7 <5) 4 
/* sending data element of different size */ 
DataLength = BUFLENtT10+i ; 
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ret = DOSALLOCSEG(DataLength, /* allocate segment */ 
(unsigned far *)&Selector, 
SHAREGIVE) ; 
if (ret) { 
printf(“\nDosAllocSeg failed, error code 
md", tat) 
DOSEXIT(1,0); 


/* give segment to receive process */ 
ret = DOSGIVESEG(Selector, 
OwnerPid, 
(unsigned far *)&RecSelector) ; 
if (ret) { 
printf (“\nDosGiveSeg failed, error code 
a, « £6C)+ 
DOSEXIT(1,0) ; 


FP_SEG(p) = Selector; /* make long pointer to seg */ 
FP_OFF (p) 0; 

/* put data in segment */ 
Spranti (text.°2d Gd “. ID. preeid. epid, at) ; 
letrepyip, \ehar far *)"’This is from preeess *): 
Letreatin, (char far *) text); 


QStat = DATA; 
prince (* ie Write to Queue: %Fs”,(char far *)p); 
ret = DOSWRITEQUEUE (QueueHandle, 

(unsigned) QStat, 

DataLength, 

(char far *}p, 

0} /* element priority N/A */ 
if (fer). 1 

printf (“\nDosWriteQueue failed: %d”,ret): 

DOSEXIT(1,0); 


DOSFREESEG(Selector); /* free the shared segment */ 
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QStat = EXIT: /* gend exit cisnal *7 


cet = DOSWRITEQUEUE (QueueHandle, 
(unsigned) QStat, 
0. /* po deta is sent */ 
(\cnae far *) NULL, 
QO); /* element pricerity N/A */ 


DOSCLOSEQUEUE (QueueHandle); 


unsigned lstrlen(s) 
char far *s; 


{ 


char far *t: 
1c a = QO: 


in BS 


while (*ttr t= *\O") 
i++: 


’ 


rerun (4) : 


void lstrcepy (target, source) 
char far *target; 
char far *source; 


{ 


char far *t: 
char tar “se; 


S = BOUrCS; 
t= Leareer; 
while (*s != ‘\0") 


a a eps 
"te = N07: 


void Istrceat (target, source) 
char far *target; 
char far *source; 
{ 
ghar tar “=; 
char far *s; 


Ss =| source; 
‘8 Lareet? 


tt=lstrlen(target); 
while (*s != ‘\0’) 

‘ete = "errs 
= 4s 
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Chapter 6 





Handling of External Events 


application. Examples of such external events are when the user enters Cntrl- 

C or Cntrl-Break to terminate the program, or when a parent process 
terminates one of its child processes. OS/2 sends signals to running processes to 
inform them of the occurrence of such events. In this way the running process can 
react to them accordingly. 

There are several types of signals, each corresponding to a different type of 
event. SigBreak is generated whenever a Cntrl-Break is entered. SigIntr is 
generated whenever Cntrl-C is pressed, but only when the keyboard is under cooked 
mode. Under raw mode, the ASCII code equivalent of Cntrl-C is sent to program 
instead (raw and cooked modes are discussed in Chapter 14). SigTerm is sent by 
the operating system to notify a process of its termination. There are also three flag 
signals, Flag A, B and G, which are used for interprocess communication. 

For each signal, there is a pre-defined signal handling routine set up by OS/2. 
These are called default actions. Whenever a user presses Cntrl-C or Cntrl-Break, 
the signals SigBreak or SigIntr, is sent to the current foreground process. If the 
process does not handle these signals, Os/2 takes the default action which is to 
send the process the signal SigTerm. If the process does not handle SigTerm, then 
control is passed to the command processor which then terminates the process. 
The signal SigTerm is also sent to a child process when its parent process uses 
DosKillProcess to terminate it. 

In Chapter 3 we discussed how signals can be used for interprocess communi- 
cation using DosSetSigHandler and DosFlagProcess. This chapter explains how 
processes can handle signals representing external events. In this way processes 
can take steps to clean up resources or finish up important tasks. 


T here are certain external events that have a bearing on the execution of an 
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Signal Handling 


Signals are handled under OS/2 very much like interrupts are handled under 
DOS. Under DOS, an external event generates an interrupt to the CPU. The CPU 
then executes a pre-defined interrupt handling routine specified by DOS or the 
BIOS. It is also possible for a DOS application to substitute its own interrupt 
handling routine for the pre-defined handling routine. When a DOS application 
no longer needs to handle an interrupt itself, it resets the pre-defined interrupt 
handling routine. 

Under OS/2, external events generate signals. For each type of signal, OS/2 has 
a predefined signal handling routine. An OS/2 application can also substitute its 
own signal handling routine for the pre-defined routine to react differently to 
external events. When the application no longer needs to handle a signal, it must 
switch back to the pre-defined routine. 

Under OS/2, however, we have background and foreground processes. Cer- 
tain signals, like SigBreak and SigIntr, are only received by the foreground process. 
To have SigBreak and SigIntr terminate a background process, the foreground 
process must trap these signals and terminate any background child process using 
DosKillProcess. Depending on the option specified by the parent process, the 
signal SigTerm generated by the function DosKillProcess can be sent to all child 
processes or one particular child process as indicated by the process ID parameter 
of the function. 

Using function DosSetSigHandler, a process can set up its own signal handling 
routine by specifying the address of the new handling routine and the signal 
number it wishes to handle. The function also returns the address of OS/2’s pre- 
defined signal handler. When a process no longer needs to handle the signal, the 
same function is used with the address returned by OS/2 to reset the signal handler 
to the default routine. 


Primary Thread and Signal Handling 


When DosSetSigHandler is used to handle a signal, the primary thread of the 
process is designated as the signal handling thread. This means that whenever a 
signal occurs, the operating system switches the primary thread from executing its 
own code to that of the signal handling routine. Because signals are time-critical 
events requiring immediate response, the primary thread is interrupted even if it 
is executing in a critical section. At the instance of interruption, suppose the 
primary thread is waiting for the return of an API function. OS/2 will not wait for 
the completion of the function, but will abort the call. When the primary thread 
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is switched back to its own sequence of instructions, an error code will be returned 
indicating that the call was aborted. File I/O API functions, however, will not be 
aborted because such calls are placed in the blocked state as soon they are made. 
Therefore, the context of the thread can be easily switched back for file I/O 
functions without aborting the call. 

Because of these constraints, if the process intends to implement a signal 
handler, it should not use the primary thread for any crucial work which may be 
corrupted when the interrupt from the signal event occurs. We recommend, in 
cases where signal handling is required, the primary thread should simply use the 
DosSleep function to wait for the signal and not do any type of processing. 

If the primary thread must be used to handle crucial work which cannot be 
interrupted, it should use the function DosHoldSignal to temporarily ignore signal 
events. Remember, a signal should be treated with the same gravity as a hardware 
interrupt. To enable signal handling again, the same function, DosHoldSignal, is 
used with a different option. 


DosSetSigHandler 


A detailed explaination of DosSetSigHandler function is available in Chapter 
3. Although this section discusses the function in terms of interprocess commu- 
nications, the same syntax, parameters, and techniques are required for signal 
handling. For this reason, a review of such information before proceeding may be 
helpful. 

The main difference between a flag event and signals such as SigIntr, SigBreak 
and SigTerm is that these signals should not be ignored by the process. Using 
DosSetSigHandler, the process can ignore a flag event, but should never ignore 
these. Upon receiving any of the above signals, a process should free its resources 
as well as notify all of its child processes to terminate before terminating its own 
execution. 

The following actions must be taken in order to setup a signal handling routine: 

® Call DosSetSigHandler with the address of the new signal handling routine, 
the signal number, and the type of action to take when the signal number 
is generated. Four kinds of action are possible: (1) taking the system 
default action, (2) ignoring the signal (3) passing control to a new signal 
handling routine and (4) sending back an error to the flagging process. 
The fourth action is used only for flag events. Note that the second action 
should not be taken to ignore a signal such as SigTerm. 


#®OS/2 returns the address of the previous signal handling routine along with 
the previous action. This information is used to reset the old signal 
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handling routine when the process no longer wants to handle the signal. 


When the signal (specified by the signal number) occurs, the primary 
thread is switched to execute the signal handling routine. For C program- 
mers, the signal handling routine should be declared as follows: 


void PASCAL far SigHandler(Sig Arg, Sig Number) 
unsigned Sig Arg:/* signal arguments */ 
unsigned Sig Number;/* signal number */ 


= For assembly language programmers the stack will contain the following 
values when control is passed to the signal handling routine: 


SS:SP The FAR return address where the primary thread was 
interrupted. 

SS:SP+4 The signal number of the occurring signal. 

SS:SP+8 The flag argument. This is used only for a flag event gen- 


erated by another process using DosFlagProcess. ‘This 
value should not be used by a signal handling routine for 
SigTerm, SigBreak, or SigIntr. 


For a C signal handling routine the system resumes execution where the 
primary thread was interrupted when the signal handling routine is com- 
pleted. The same is true for an assembly language signal handling routine 
which exits using the intersegment return instruction. The assembly 
language routine, however, can change the stack frame to a pre-defined 
state and can jump to another routine within the program. 


DosHoldSignal 


With DosHoldSignal the calling process can disable or enable the processing of 
signals. When signal processing is disabled the process recognizes a signal sent to 
it but does not accept it. The process essentially refuses to act on any signals sent 
to it by the operating system. This call is used by subsystems, device drivers, or any 
other code which should not be interrupted by the operating system. For example, 
during the execution of a critical section used to access an SRR, the latter would 
be corrupted if an interruption occured. 

As explained earlier, a well-intentioned program should not ignore signals sent 
to it by the operating system. DosHoldSignal should only be used to refuse signals 
for a short period of time. In other words, signals should be treated with the same 
gravity as a hardware interrupt. 
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This function requires only one parameter, AcizonCode, which specifies whether 
to disable or enable signal processing. The operating system allows a process to 
disable the signal more than once, but for every disable request, there must be a 
corresponding enable request. OS/2 keeps track of an internal Count variable 
adding one or subtracting one whenever a disable or enable call is made. 
Whenever the count is zero, signal processing is enabled. If the count becomes less 
than zero, an invalid function error occurs. This feature permits the recursive use, 
or nesting, of this function. 


DosHoldSignal (ActionCode) 


unsigned ActionCode; /* signal process disable or enable option */ 





Examples 


/* SENDSIG.C 


PARENT PROCESS: NONE 
CHILD PROCESS: SENDSIG2.C 


* This program demonstrates how to use: 
DosSetSigHandler, 
DosSendSignal, 
DosHoldSignal. 
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sendsig.exe simply uses DosSendSignal to send Cntr1l-C or Cntrl- 
Break to SENDSIG2. 


Note: the return code for DosSendSignal should be examined. 

If the error code is 162, “signal pending”, the sending process 
should send the signal again. This error indicates that the 
receiving process is still processing the previous signal. 


tf 


include <doscalls.h> 
dFinclude <subcalls.h> 
include <stdio.h> 


define SIGINTR 1 ie Copied. #7 
define SIGBREAK 4 /* Gnhtrl-Break */ 
#fdefine ERROR _SIGPENDING 162 /* SIGNAL is pending */ 


##tdefine ERROR_NO_SIGNAL_SENT 205 /* signal is refused */ 
/* because of DosHoldSignal */ 


char PgmName[] = “SENDSIG2.EXE”; 


void -sendsignal’ (); 


void main (){ 
/* data for DosExecPem */ 


unsigned i; 
unsigned PID; 


unsigned ret; 

struct ResultCodes ReturnCodes:/* return code structure */ 
printf (“\nSpawn SENDSIG2.EXE”) ; 

ret = DOSEXECPGM ((char far *)0, 


Os, 
i, /* Asynchronous Execution */ 


} 
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(ehar far *)d, /* argument */ 
(Shar far *)0, J* wall enepter “7 
&ReturnCodes, 


(char far *)PgmName) ; 


printt (“\nsleep for 1 -«setond.s..*): 
DOSSLEEP((long) 1000);/* sleep for 1 second allowing */ 
/* child process to catch up */ 


for (1=0: i<3% att) | 


sendsignal (SIGINTR, ReturnCodes.TermCode_PID) ; 
sendsignal (SIGBREAK, ReturnCodes.TermCode_PID) ; 

} 

DOSCWAIT (1, /* wait until child precess end */ 
O ’ 


ietruct ResultGodes far *) SReturnCodes, 
(unsigned far *)&PID, 
ReturnCodes.TermCode_PID) ; 

DOSEXIT (1,0) 3 


void sendsignal(signal, pid) 
unsigned signal; 
unsigned pid; 


{ 


unsigned ret; 


while (1) { 
printt(“\nbendine Sishal: Ud" ,signal): 
ret = DOSSENDSIGNAL (pid, 
signal); 
/* if signal is pending send again */ 
if (ret) { 
if (ret == ERR_SIGPENDING) { 
DOSSLEEP (OL) ; (* wait a few tick */ 


continue; 
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if (ret ++ ERROR_NO_SIGNAL_SENT) 
printf("\Receiving process refuses signal"); 
else 
printf(“\nSendSignal failed, error code 
6" , fet) s 
} 
break; 


/* SENDSTG2.C 


PARENT PROCESS: SENDSIG.C 
CHILD PROCESS: NONE 


This program demonstrate how to capture termination signals that 
can be sent by a parent process via DOSKILLPROCESS, DosSendSig- 

nal, or by the user by pressing Cntrl-C or Cntrl-Break. In raw 

keyboard mode cntrl-C will not generate a SIGINTR. 


Also it demonstrates how to use DosHoldSignal to stop receiving 
Signals. : 


Every time a cntrl-C or ecntrl-Break is pressed or sent, two 
Signals are generated: SIGINTR or SIGBREAK and SIGTERM. There- 
fore, when the receiving program wants to refuse terminition 
termination, it must trapped all signals. 


SENDSIG2.EXE will simply invoke DosSetSigHandler, then sleep in 
a loop to wait for the signal. 


After receiving three signals, it will stop recieving signal 
using DosHoldSignal. 


Note: 
- The signal handler must “acknowledge” that a signal has been 


trapped in order to receive the next signal. 


- OS/2 will processe SIGBREAK as SIGINTR and sends the signal 
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number to the handler''as SIGINTR 


- You can have one signal handler to handle multiple type of 
signals and flags, 
signal. 


or to have a separate handler for each 


This program will not process cntrl-C but will quit when cntrl- 
break is pressed. 


my 


include <doscalls.h> 
include <subcalls.h> 
include <stdio.h> 


#define 
define 
#define 
+#define 
define 
+#define 


define 
define 
+#define 
define 
+#define 


SIGINTR 
SIGTERM 
SIGBREAK 
SIGFLAGA 
SIGFLAGB 
SIGFLAGC 


SIG_DEFAULT 
SIG_IGNORE 
SIG_CATCH 
SIG_ERR 
SIG_ACK 


/* possible signals */ 


/* parameters for Action parameter */ 


/* need to prototype the sig handler routine to satisfy the 
compiler */ 


void pascal far sig handler(); 


unsigned Quit; 
unsigned count =0; 


void maint) { 


/* global flag */ 
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void (pascal far *prev_address)(); /* SIGINTR - prev address */ 
unsigned prev_action; 


void (pascal far *prev_address2)(); /*-SIGBREAK - prev-address*/ 
unsigned prev_action?2; 


void (pascal far *prev_address3)(); /* SIGTERM - prev address */ 


unsigned prev_action3; 
unsigned ret; 
printt(“*\n Sendeie2: trapping Cntrl-C or Ghtri<Break:..."); 


/* trap eigtal */ 

ret= DOSSETSIGHANDLER(sig handler, /* signal handler address */ 
(unsigned long far *) &prev_address, 
(unsigned far *) &prev_action, 


SIG_CATCH, /* accept signal */ 
SIGINTR) ; /* teap entrlsc */ 
if (ret) { 


printf ("\nDosSetSigHandler for SIGINTR failed. Error code 
as. Set) 3 
DOSEXIT (1,0); 
} 
ret= DOSSETSIGHANDLER(sig_handler, /* signal handler address */ 
(unsigned long far *) &prev_address2, 
(unsigned far *) &prev_action2, 
SIG_CATCH, ‘* aceept signal */ 
SIGBREAK) ; /* trap entrl-Break */ 


if (ret) { 

printf(“\nDosSetSigHandler for SIGBREAK failed.Error code 
Vea 5 PeELs 

DOSERZIT(1,0) ; 


ret = DOSSETSIGHANDLER(sig handler, 
(unsigned long far *) &prev_address3, 
(unsigned far *) &prev_action3, 
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SIG_CATCH, 
SIGTERM) ; 


if (ret) { | 
printf(“\nDosSetSigHandler for SIGTERM failed. Error code 
td." £et)s 
DOSEXTT (1,0) 3 
} 


Quit = 0; * wait until quit flas ise ser *7 
/* by the signal handler*/ 
while (!Quit) 
DOSSLEEP((long)10000); /* sleep for 1 seconds */ 


printf("\n Sendsig2: hold signal"); 


ret = DOSHOLDSIGNAL (1) /*disable signal*/ 
DOSSLEEP ( (Long) 5000) /*sleep for 5 seconds*/ 
ret = DOSHOLDSIGNAL(0) ; /*enable signal*/ 


printf("\n Sendsig2: restore old handler") ; 


/* Restore previous signal handler. */ 


ret= DOSSETSIGHANDLER (prev_address, 
(unsigned long far *) O, 
(unsigned far *) 0, 
prev_action, 
SIGINTR) ; 


if (rat) { 
printt(“\n Cannot restore SIGINTR. Error code %d”, 
tet); 
DOSEXIT (1, @) ; 
} 


ret= DOSSETSIGHANDLER (prev_address?2, 
(unsigned long far *) 0, 
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(unmeiened far *) 0, 
prev_action2, 
SIGBREAK) ; 


if (rer) { 

prantt (* \o Cannot restore SIGBREAK. Error code %d.,” 
ret) ; 

DOSEXIT(UL, 0) : 


’ 


ret= DOSSETSIGHANDLER (prev_address3, 
(unsigned long far *) O, 
(unsigned far *) O, 
prev_action3, 
SIGBREAK) ; 


if (retry 4 


Orantr(” a Cannot restore SIGTERM. Error code %d.,”, 
ret); 


DOSEXIT(1,0)% 
DOSEXIT(1,0) : 
} 
/* OS/2 will process SIGBREAK as SIGINTR and will send the 


signal number to the handler as SIGINTR */ 


void paseal far sig_handler(sig arg, sig_num) 
unsigned sig_arg, sig num; 
{ 


Lat ret; 
/* we do not want to acknowledge the flag before the 
printf statement to insure that another signal will 


not be received while printing. */ 


printfi(“*\n Sendsig2: recv signal: %d, arg:%d”, 
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Sig nim,6sie are): 


Couriers: 
4£ (eotink J=— 3) 
Sue = 1s 


/* acknowledge that the signal is received */ 
ret = DOSSETSIGHANDLER ((void (far *)()) OL, 
(unsigned long far *) O, 
(unsigned far *)0O, 
SIG_ACK, 
sig num) ; 


Lf (ret) 
printf(“\n Acknowledge Flag %d failed. Error code: %d”, 


sig num, ret); 


} 
/* GCNTRLC.C 


This program demonstrate how to capture terminate signals that 
can be send by a parent process via DOSKILLPROCESS or from the 
user by pressing Cntrl-C or Cntrl-Break. In raw keyboard mode 
cntrl-C will not generate a SIGINTR. 


Every time a cntrl-C or cntrl-Break is pressed, two signals are 
generated SIGINTR or SIGBREAK and SIGTERM. If a program does not 
want to be terminated via a user input cntrl-C it must trap all 


Signals. 


CONTRLC.EXE will simply invoke DosSetSigHandler, then sleep in a 
loop to wait for the signal. It is recommended that the primary 
thread or thread 0 should not do any kind of processing in order 
to guarantee that all signals will be captured. 


In this program, the primary thread will simply wait in a Sleep 


loop. 


Note: 
- The signal handler must “acknowledge” that a signal has been 
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trapped in order to receive the next signal. 


- OS/2 will process SIGBREAK as SIGINTR and will send the signal 
number to the handler as SIGINTR 


- You can have one signal handler to handle multiple type of 
Signals and flags, or to have a separate handler for each sig- 
nal. 


This program will not process cntrl-C but will quit when cntrl- 
break is pressed. 


oF | 


include <doscalls.h> 
include <subcalls.h> 
include <stdio.h> 


define SIGINTR 1 /* possible signals */ 
define SIGTERM 3 
/t}define SIGBREAK 4 
Ht}define SIGFLAGA 5 
Ht}define SIGFLAGB 6 

4 


+#define SIGFLAGC 


define SIG_DEFAULT 0 /* parameters for Action parameter */ 
}tdefine SIG_IGNORE 1 
ttKdefine SIG_CATCH 2 
define SIG_ERR 3 
HHdefine SIG_ACK mh 


/* need to prototype the sig handler routine to satisfy the 
compiler: */ 

void pascal far sig handler(); 

unsigned Quit; /* giobal, flag, */ 

unsigned count =0; 


void main() { 


void (pascal far *prev_address)(); /* SIGINTR - prev address */ 
unsigned prev_action; 
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void (pascal far *prev_address2)(); /* SIGBREAK - prev address*/ 
unsigned prev_action?2; 


void (pascal far *prev_address3)(); /* SIGTERM - prev address*/ 
unsigned prev_action3; 


unsigned ret; 


print?’ (°\nThis program is trapping Chtrl-C or Untrl-Break ...")4 
printf(“\nPress Cntrl-C or Cntrl-Break three times to quit”); 


/* trap signal, */ 
ret= DOSSETSIGHANDLER(sig_handler, /* signal handler address */ 
(unsigned long far *) &prev_address, 
(unsigned far *) &prev_action, 
SIG_CATCH, /* accept sienal */ 
SIGINTR) ; /* -erap cftril-c */ 


if (ret) { 
printf(“\nDosSetSigHandler for SIGINTR failed. Error code 
ho.” y. Cet) 4 
DOSEAITE I, 0) s 
} 
ret= DOSSETSIGHANDLER(sig_handler, /* signal handler address */ 
(unsigned long far *) &prev_address2, 
(unsigned far *) &prev_action2, 


SIG_CATCH, /* accept signal */ 
SIGBREAK) ; /* trap cntril-Break */ 
if (ret) { 


printf (“\nDosSetSigHandler for SIGBREAK failed. Error code 
ia” « Bec) % 
DOSEXIT (1,0) ; 


ret = DOSSETSIGHANDLER(sig_handler, 
(unsigned long far *) &prev_address3, 
(unsigned far *) &prev_action3, 
SIG_CATCH, /* accept signal */ 
SIGTERM) ; /* trap terminate signal*/ 
if {ret} | 
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printf(“\nDosSetSigHandler for SIGTERM failed. Error code 
ed.”, ret); 
DOSEXIT (1,0): 


Quit = 0; /* loop until three contrl-c is pressed */ 
while (!Quit) 
DOSSLEEP ( (long) 10000) ; 


/* Restore previous signal handler. */ 


ret= DOSSETSIGHANDLER(prev_address,/* signal handler address */ 
(unsigned long far *) 0, 
(unsigned far *) 0, 
prev_action, 
SIGINTR) ; 
1 (ret) { 
erintt(*\a Cannot restore SIGINTR. Error code %d”, 
ret); 
DOSEXIT (1,0) ; 
} 


ret= DOSSETSIGHANDLER (prev_address2,/* signal handler address */ 
(unsigned long far *) 0, 
(unsigned far *) 0, 
prev_action?2, 
SIGBREAK) ; 
Lf (ret) { 
printf(“\n Cannot restore SIGBREAK. Error code %d.,”, 
ret); 
DOSEXIT (1,0) 
} 


ret= DOSSETSIGHANDLER (prev_address3,/* signal handler address */ 
(unsigned long far *) O, 
(unsigned far *) 0, 
prev_action3, 
SIGBREAK) ; 
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if (ret) { 

printt (* \n Cannot restore SIGTERM. Error code %d.,”, 
ret); 

DOSEXAET (1,0) 
} 


DOSEXIT(1,0); 
} 


/* OS/2 will process SIGBREAK as SIGINTR and will send the 
signal number to the handler as SIGINTR */ 


void pascal far sig_handler(sig_arg, sig num) 

unsigned sig _ arg, sig num; 

{ 

Int ret; 
/* we did not want to acknowledge the flag before 
the printf statement to insure that another signal 
will not be received while printing. */ 


printf (“\nReceiving Signal: %d, arg: %d”,sig_num,sig arg) ; 
eountTT; 
Lf (count. 2=— 3) 

St =. 14 


/* acknowledge that the signal is received */ 
ret = DOSSETSIGHANDLER ((void (far *)()) OL, 
(unsigned long far *) 0, 
(unsigned far *)0O, 
SIG_ACK, 
sig num) z 


Lf (rei) 
printf(“\nAcknowledge Flag %d failed. Error code: %d”, 
sig num, ret); 


Chapter 7 


Date and Timer Services 





esides providing basic time and date functions for the system clock, OS/2 
provides a set of advanced timer functions that allow applications the 
ability to perform time-sensitive operations. Applications use these ad- 
vanced timer functions in conjunction with system semaphores to control the 
execution of processes and threads, analogous to the way events in the external 
world can be orchestrated with the aid of a stopwatch. An application can set 
up a timer that notifies a process or a thread when a certain time-limit has 
expired, or the timer can be set up to periodically notify a process or a thread. 
This chapter discusses the date/time functions, and other API functions 
which are used to implement timer services. Since timer functions make use of 
semaphores, you should have a good understanding of semaphores before 
trying to use these timer services. Because they use semaphores these functions 
are not available in compatability mode. 


Date Functions 


OS/2 provides two functions used to obtain or set the current date and time 
of the system clock: DosGetDateTime and DosSetDateTime. As mentioned in 
Chapter 2, a process can use DosGetInfoSeg to obtain the pointers to the seg- 
ments containing global descriptor and local descriptor information. The cur- 
rent date and time information are constantly updated by OS/2 as part of the 
global descriptor information. Thus a process can use these pointers to obtain 
the current date and time without using the function DosGetDateTime. Dos- 
GetDateTime and DosSetDateTime are provided for programs designed to run 
in the Family API environment since DosGetInfoSeg is not available in a system 
running under DOS. 


274 Advanced Programmer's Guide to OS/2 


DosGetDateTime 


DosGetDateTime obtains the current date and time information of the sys- 
tem clock, and writes this information to a data structure. This function re- 
quires a pointer to this data structure. The format of the structure is as follows: 


etruct-DateTimes{ 


unsigned char Hours; /* current hour, from 0-23 */ 
unsigned char Minutes; /* errant minmite,. from 0-59 */ 
unsigned char Seconds; /* current second, from 0-59 */ 
unsigned char Hundreths; /* current hundredths of a 
second, from 0-59*/ 
unsigned char Day; /* eurrent day, from 1-31 ty 
unsigned char Month; /* eurrent month, from 1-12 */ 
unsigned char Year; /* current year, from 80-79 
(for 1980-2079) */ 
unsigned char TimeZone; /* number of minutes from 
GMT */ 


unsigned char DayofWeek; /* current day of week, from 0- 
6 with Sunday equal to 0) */ 
} 


The TimeZone value represents the number of minutes difference between 
the current time zone and Greenwich Mean Time (GMT). The value returned 
would be negative if the time zone is after GMT and positive if it is before GMT. 
For example, the value returned for eastern standard time (EDT) would be 300 
minutes, or 5 hours before GMT specified by a positive value. 


DosGetDateTime (DateTime) 


struct DateTime far *DateTime; /* a data structure to which the current 
date and time info is written*/ 
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Compatability Mode Restriction 


None 


DosSetDateTime 


The function DosSetDateTime sets the current date, time, and timezone of 
the system. This function requires a pointer to the data structure containing 
the values OS/2 will use to set the system clock. The data structure should 
contain the following fields: 


erruct SetDateTime {| 


unsigned char Hours; /* earrent hour, from 0-22 */ 

unsigned char Minutes; /* @urrent minute, from 0-59 */ 

unsigned char Seconds; /* current second, from 0-59 */ 

unsigned char Hundreths; /* current hundredths of a 
second, from 0-59*/ 

unsigned char Day; /* cttrrent dag; irem 1-31 -*/ 

unsigned char Month; /* current month, from 1-12 */ 

unsigned char Year; /* current year, from 80-79 
(for 1980-2079) */ 

unsigned char TimeZone; /* number of minutes from GMT*/ 


The process does not need to set the current day of the week; OS/2 auto- 
matically calculates this value from the information given it. 


DosSetDateTime (DateTime) 


struct SetDateTime far *DateTime; /* structure containing current date and 
time info */ 
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Compatability Mode Restriction 


None 


Examples 


/* DATEFUNC.C 


This program demonstrates how to use DosGetDateTime and Dos- 
SetDateTime */ 


#Finclude “stdio.h” 
include “doscalls.h” 


main () 
{ 


struct DateTime datetime: 


DOSGETDATETIME( (struct DateTime far *)&datetime): 


PEAntt (* \WneoUr: %d”, (int) datetime.hour); 

printt (* \wMinute: ya”, (int) datetime. minutes) : 
orintt (“\nSeconds: “0”, (int) datetime. seconds) ; 
printf (“\nHundredth: %d”,(int) datetime.hundredths) ; 
printt ¢* \n\nDay: *d”, (int) datetime.day) ; 

printf (“\nMonth: “i”, (int) datetime.month) ; 
print: (“\nitear: %d”, (int) datetime.year); 

printf (“*\nTimeZone: %d”,datetime.timezone) ; 
printf(“\nDay of week: %d”, (int) datetime.day_of_week) ; 


/* change the minute */ 
datetime.minutest' ; 


/* get the date and.time */ 
DOSSETDATETIME (| Cetruct DateTime far *) Gdatetime) : 
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Timer Functions 


Timer functions are used by applications for time-sensitive or time-interval 
based operations. For example, in a local area network environment, a net- 
work monitor can periodically check the status of certain resources on the 
network. These resources include the file server, the SNA gateway, the termi- 
nal server, or any workstations on the network. The key point is that these 
resources must be checked periodically at exact time-intervals. Using timer 
functions, a program can be written to dial-up a database service and download 
stock quotes every hour. Also, communication programs can periodically 
check whether a connection is still on-line or has gone off-line. Timer func- 
tions are also used in conjunction with other API functions like DosReadAsync 
and DosWriteAsynch which allow a thread to read or write data asynchronously, 
and to continue executing without having to wait for the I/O operation to be 
completed. 

Timer functions under OS/2 are used in conjunction with system sema- 
phores; they do not work with RAM semaphores. There are four timer func- 
tions, DosSleep, DosStartAsync, DosTimerStart, and DosTimerStop. DosSleep 
halts the execution of the calling thread for a specified number of milliseconds. 
It is the simplest of these functions. The other timer functions allow the calling 
thread to start and stop an asynchronous timer. An asynchronous timer executes 
(keeps time) while the thread continues to execute. Such a timer can be set up 
to change the status of a semaphore (as a sort of alarm clock) after a certain 
amount of time has passed and then discontinue its execution, or it can be set 
up to change the status of a semaphore periodically until it is explicitly discon- 
tinued by the thread. 

Function DosStartAsync allows the application to set an asynchronous count- 
down timer that ticks for a certain number of milliseconds. When the timer 
expires, the function automatically clears a specified semaphore, then termi- 
nates. This function differs from the function DosSleep, in that the execution 
of the calling thread is not suspended until the timer expires. 

The thread can also stop a timer before the previously specified time interval 
expires using the function DosTimerStop. 

Suppose the application needs to check the status of a device 30 minutes 
after every access. Once the device is accessed, the application can use the 
function DosStartAsync to set-up a 30 minute countdown timer. After 30 min- 
utes the function clears a prespecified semaphore. The application can set up 
a separate thread to wait for the semaphore to be cleared. Once the sema- 
phore is clear, the waiting thread wakes up and checks the status of the device. 
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This setup naturally requires that the semaphore in question has been set by 
the application before calling the function DosStartAsync. 

DosTimerStart provides a different type of timer service. Using this function 
the application can set up an asynchronous periodic timer which clears a sema- 
phore repeatedly at the end of a timeinterval. DosTimerStart and DosStart- 
Async differ in that DosStartAsync is a countdown clock which alerts the appli- 
cation onle after a certain predefined time-interval has expired, while DosTim- 
erStart is like a clock which is set to ring continuously at a time-interval chosen 
by the programmer. Of course, instead of ringing these clocks clear a prespeci- 
fied semaphore. 

If, for example, a process needs to dial up a database service every hour to 
download stock quotes, the function DosTimerStart can be set up to clear a 
semaphore every hour in order to provide a starting time. The status of this 
semaphore is used for notification purposes, the process sets up a separate 
thread that waits specifically on this semaphore. When the semaphore is cleared, 
the thread wakes up and performs the download operation. Once the down- 
load is completed, the thread resets the semaphore and waits for the timer to 
clear it again. DosTimerStart continues to clear the semaphore at an hourly 
interval until the timer is stopped using function DosTimerStop. 

Note that it does not matter to the two timer functions, DosStartAsync and 
DosTimerStart, whether a semaphore is previously set or not. They will exe- 
cute either way, simply putting the semaphore in the clear state at the end of a 
specified interval. In order to know whether a timer has expired or not, the 
application must make sure that the semaphore was set to start with (using 
DosSemSet). If the semaphore is in the clear state when the timer functions 
are invoked, the functions are rendered useless because there is no way the 
calling thread can determine whether a timer has expired or not. 


Considerations for Timer Functions 


The main problem with using timer functions is the possibility that threads 
waiting on the timer may not detect the semaphore clearing event at the instant 
during which it occurs. This problem is inherent to the OS/2 scheduling sys- 
tem. For example, suppose a thread is waiting for the expiration of a 5-second 
asynchronous timer. If the system is busy, the scheduler may keep the thread 
in the ready state for a period longer than 5 seconds. While in the ready state, 
a thread cannot determine a change in a semaphore status (it can only check 
the status of a semaphore when it is running). Consequently the thread waiting 
on the timer will wake up after the timer has expired, but it is possible that this 
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will be some time after 5 seconds has passed. ‘Therefore we see that timer 
functions under OS/2 suffer from an accuracy problem. This problem can be 
minimized by giving a high priority to the waiting thread, but even this does 
not eliminate the problem completely. For the DosStartTimer function, it is 
possible that the semaphore can be cleared (that the timer interval might 
expire) more than once while the thread is waiting in the dispatcher queue. 
This is very likely if the time interval indicated is very short (in terms of millisec- 
onds). | 

Though it is impossible for an application to use the timer functions with 
absolute accurracy, it can determine an exact elapsed time count using the 
global descriptor information (returned by DosInfoSeg) by monitoring the 
milliseconds or seconds field. The milliseconds field should be read just prior 
to calling the timer function, and then again when the waiting thread resumes 
execution. The difference between these two values represents the true time 
elapsed during the timer function. 

The millisecond field rolls-over (begins at 0 again) after a few weeks. The 
process should take this into account if it waits for longer than that. The date 
fields and the elapsed seconds field, however, remain correct and can be used 
to adjust for any roll-over. Also the millisecond field is based on the clock 
interrupt of the CPU. In situations where hardware devices disable all inter- 
rupts for periods longer than than a clock-tick interval, this field might not be 
accurate. We recommend that the programmer use the elapsed second field as 
an indicator of elapsed time, if system interrupts will be disabled often and for 
long periods of time. 

Timer functions are accurate only to one or two clock ticks. The smallest 
value that can be set is a millisecond and it is rounded to the next clock tick. 
To determine the duration of the clock tick, the application can examine the 
Timer_Interval field returned in the global descriptor information by function 
DosGetInfoSeg. 

Timers are a system resource maintained by OS/2. It can maintain a limited 
number of timers at any one time. The maximum number of timers allowed by 
OS/2 is equal to the maximum number of threads for which the system is 
configured. If, for example, in the configuration file, (config.sys), the maximum 
number of threads for the system is defined as 200, the maximum number of 
timers for the configured system is also 200. OS/2 recommends that each 
application should use no more than 6 timers at once. This is because unless 
the system is a dedicated one, there may be other other applications running 
concurrently using up threads. 
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DosSleep 
The syntax of DosSleep is discussed on page ##. 


DosTimerAsync 


DosTimerAsync sets up an asynchronous timer that ticks for a specified time 
interval. At the expiration of the timer, the function clears a specified sema- 
phore to notify the calling thread (or a thread that has been set up by the 
calling thread to wait on the semaphore) that time’s up. The thread must call 
this function again to restart the countdown. Since the timer runs asynchro- 
nously, the calling thread can continue its own execution and does not have to 
wait while the timer counts. (This function can be viewed as an asynchronous 
version of the function DosSleep which forces the calling thread to wait until 
the expiration of the timer). For a more detailed discussion of this function, 
please refer to the previous sections. 

To stop the timer before time is up, the calling thread can issue the function 
DosStopTimer. Ifa timer is stopped prematurely with DosStopTimer, then the 
semaphore which it controls is not cleared. When this happens any other 
threads waiting on the semaphore cannot assume anything about its state.’ In 
order to reactivate these threads, the application will have to explicitly clear the 
semaphore. 

Since OS/2 implements DosTimerAsync by starting an asynchronous thread, 
it is important to know that this thread is included in the count of threads 
which are active within the system. Remember, there is a limit to the number 
of running threads that an application can start. 

DosTimerAsync expects three parameters: the length of the time interval 
(Timelnterval), the semaphore handle of the system semaphore that is cleared 
once the timer expires, and an address to the timer handle (Handle) which is 
returned by the function. The timer handle is used by the calling thread to 
identify and stop the timer before its expiration using the function DosStop- 
Timer. 


DosTimerAsync (Timelnterval, SemHandle, Handle) 


unsigned long TimelInterval; /* time interval to count down in 
milliseconds */ 


"Multiple threads can be made to wait on a timer using the level-triggered function DosMuxSemWait. 
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unsigned long SemHandle; /* system semaphore handle */ 


unsigned far *Handle; /* pointer to timer handle to be returned */ 





Compatability Mode Restriction 


Not available 


DosTimerStart 


DosTimerStart sets up an asynchronous timer which penodically clears a speci- 
fied semaphore after a set time interval. If the time interval is set to 30 seconds, 
this means that the timer clears the semaphore every 30 seconds until it is 
stopped. The calling thread can check for the expiration of the time interval 
by waiting on the semaphore. When the semaphore is cleared, time is up. 
Since the timer runs asynchronously, the calling thread can continue its own 
execution without waiting for the timer. To check for the timer, it can set up 
another thread that waits for the semaphore. (For a more detailed discussion 
of this function, please refer to pages 3 through 5 in this chapter). 

To stop the timer, the calling thread must issue the function DosStopTimer. 
A periodic timer must be explicitly stopped or else it just keeps running, using 
up system resources, until its owner process terminates. When the timer is 
stopped in this manner, any other threads waiting on this semaphore cannot 
assume anything about its state. 
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DosTimerStart expects three parameters: the time interval specification 
(Timelnterval), the semaphore handle of the system semaphore that is repeat- 
edly cleared whenever the timer interval expires, and an address to the timer 
handle (Handle) which is returned by the function. The timer handle is used by 
the calling thread to identify and stop the timer when it is no longer needed 
using DosStopTimer. 


DosTimerStart (Timeinterval, SemHandle, Handle) 


unsigned long TimelInterval; /* time interval in milliseconds */ 
unsigned long SemHandle; /* system semaphore handle */ 
unsigned far *Handle; /* pointer to timer handle to be 


returned */ 





Compatability Mode Restriction 


Not available 


DosTimerStop 


DosTimerStop stops an asynchronous timer started by either the DosStart- 
Async or DosStartTimer function. This function simply deletes the timer thread. 
Any other threads waiting on the timer semaphore can assume nothing about 
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its state after DosTimerStop has been called. The application will have to take 
steps to put the semaphore in a consistent state. 

The timer started by DosStartAsync stops running once the specified time 
interval has expired. A timer started by DosStartTimer runs indefinitely and 
must be stopped by another thread once the process no longer needs the 
timer’s services or when the process terminates. 

DosTimerStop only expects one parameter: the handle of the timer to be 
stopped. The handle of a timer is the value returned to the calling thread by 
function DosStartAsync or function DosStartTimer. 


DosTimerStop (Handle) 


unsigned Handle; /* handle of timer to be stopped */ 





Compatability Mode Restriction 


Not available 


Examples 
/* TIMER.C 
This program demonstrates how to use DosTimerAsync to set up an 


asynchronous timer, DosTimerStart & DosTimerStop to set up a 
periodic timer. 


Note: DosSemWait returns an error code 121, ERR_SEMTIMEOUT, if 
the waitparameter is 0 or greater than 0, specifying the time to 
wait for thesemaphore to clear. 


at 


#include “stdio.h” 
include “doscalls.h” 
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ffdefine NOEXCLUSIVE 1 
#tdefine ERR_SEMTIMEOUT121 /* semaphore wait time out */ 
char SemName[] = “\\SEM\\TIMER”; 
main () 
{ 
long semhandle; /* semaphore handle, use for 
DosCreateSem */ 
unsigned timerhandle; /* use for DosTimerAgyne */ 


long TimeInterval; 
unsigned i, ret; 
/* create a system semaphore */ 
DOSCREATESEM (NOEXCLUSIVE, /* non-exclusive system sema- 
phore */ | 
(long far *)&semhandle, 
(char far *)SemName) ; 


DOSSEMSET (semhandle); /* set the system semaphore */ 


/* start the asyne timer */ 


TimeInterval = 3000L; /* 3 seconds */ 
DOSTIMERASYNG (TimelInterval, 
semhandle, 


(unsigned far *)&timerhandle) ; 


printf(“\nWaiting for Asynchronous Timer”) ; 
DOSSEMWAIT (semhandle, (long) -1):/* wait until the */ 
/* semaphore is clear */ 
DOSSEMSET (semhandle) ; 
TimeInterval = 1000L; /* 1 second */ 


DOSTIMERSTART (TimelInterval, 
semhandle, 
(unsigned far *)&timerhandle) ; 
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i= 0; /* wait for the semaphore 3 time */ 
printf(“\nWaiting for Semaphore to clear,..7): 
while (1) { 

ee 


DOSSEMWAIT (semhandle, (long) -1); 
printr(“\n Semaphore elear: “d time({s)”,i): 
DOSSEMSET (semhandle) ; 
if (1 >= 3) | 
printt (*instop Timer”); 
DOSTIMERSTOP(timerhandle) ; 
break; 


} 


printf(“\nWaiting for semaphore to clear without timer”); 


ret = DOSSEMWAIT(semhandle, 
S000L)t/* wait 3 second for the semaphore to clear*/ 


if (fet = ERR. SEMTIMEOUT) 
orintt(*\nfemaphore did not clear”): 


Chapter 8 


Error Handling and Message 
Retrieval 


he processing of errors is a necessary part of any application. A complete 

application should anticipate all possible errors and take steps to resolve or 

explain them to the user in a comprehensive fashion. With this in mind, 
OS/2 provides applications with extensive facilities for error handling. 

One of the improvements of OS/2 over DOS is the uniformity of all returned 
error code values. All OS/2 API functions return a zero when the function is 
successful or a non-zero error code specifying the error number when it is 
unsuccessful. For assembly language programs, the error code is simply returned 
in register AX. Most DOS functions, however, set the carry flag to indicate that an 
error has occurred and store the error code in register AX. But with DOS functions 
written for version 2.1 or later, the carry flag is not set, and FCB function calls return 
an FFH value in register AL to indicate an error. 

The number of errors that can be returned for a particular function might be 
very large, and programs often use a large number of API functions. Ifapplications 
had to determine and localize each error on their own, the complexity of the 
coding task and the processor overhead would be counterproductive. In order to 
relieve applications of this burden OS/2 provides the function DosErrorClass. 
When an application receives an error code, it can pass this value to DosErrorClass 
which returns information as to the type of error, its location within the system, and 
even a recommendation as to the course of action the program should take. 

OS/2 also allows a process to disable hard error processing and trap exceptions. 
Exceptions are caused by errors within the running thread which are generated by 
the 80286 CPU or the math coprocessor. Hard errors are those caused by problems 
such as media defects on the diskette or hard drive, the diskette not in the drive, 
an unformatted diskette in the drive, parallel printer out of paper or disconnected, 
etc. Hard errors are usually handled by DOS with a message displayed on the video 
screen plus the infamous query “Abort, Retry, Fail or Ignore?”. Depending on the 
user response, DOS either aborts the program, retries the operation, returns a 
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failure error to the program, or ignores the error and continues operation. The 
OS/2 handler hard error is much better than DOS with more comprehensive 
messages explaining the error. 

An exception is usually caused by problems with the software. Exceptions 
should be trapped by the program itself in order to determine their cause, 
hopefully fix them, or at least close opened resources before termination. Func- 
tion DosSetVec can be used to trap several 80286 exceptions. Other than problems 
of media defects on the hard drive, or failures of certain system adapters, most 
frequent hard errors can be fixed by the user. Therefore, itis usually advantageous 
to allow OS/2 to handle the hard error. A program can, however, use the function 
DosError to instruct OS/2 to bypass the user in cases of a hard error or exception. 

Since errors do not occur very often within a program, OS/2 provides an 
external message retrieval facility to reduce the program’s memory requirements. 
Under OS/2, error messages can be stored apart from the executable “.exe” file. 
They can be stored in a file that is loaded on demand, not when the application is 
invoked. Whenever it needs a message, the application just reads it from the disk. 
This facility will make life much easier for programmers who’ve had to shorten 
help messages in order to fit into the memory requirements of the C small model. 

The message retrieval system can also be used for other types of messages 
displayed by the program. An application can manipulate external help messages, 
additional information, or prompting. This ability to place a program’s messages 
in an external file, apart from its executable code, greatly simplifies the translation 
of applications from language to language. The textin the message file will merely 
have to be translated, rather than changing the source code to include the 
translated messages. Since personal computers are used all over the world, the 
OS/2’s message retrieval facility will allow developers to easily address a global 
audience. 


DosErrorClass 


Using the function DosErrorClass, an OS/2 process can determine the type of 
error received after an API function call. If an error occurs (after any function 
call) ,a non-zero value is stored in the AX register. For C programs, the C compiler 
returns the error code back to the calling thread. The following API function call 
illustrates how a C program can receive an error number from the DosRead API 
function. 


threadunsigned error; 
error = DosRead (fd, buffer, length, byteread) 
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If the variable error contains a non-zero value after the completion of the 
function, then an error has occurred. The value of erroris the same value returned 
by OS/2 to the AX register. 

The application can then obtain information on the error code, and a recom- 
mendation as to what action to take, by passing the error code to the function 
DosErrClass. DosErrClass requires the error code and returns three values: the 
class of the error (class), the recommended action (action), and the locus of the 
error (locus). 

The value of class explains the type of error. The listing and value of all error 
classes are as follows: 
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The recommended action (action) provides the process with an appropriate 
response to the error. The values returned for the recommended action parame- 
ter are as follows: 
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The locus of the error (locus) tells the process which system device caused the 
error. The values and meanings of this parameter are as follows: 
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DOSERRCLASS (ErrorCode, Class, Action, Locus) 


unsigned ErrorCode; /* error code number returned by 
OS/2"% 
unsigned far *Class; /* pointer to the error class to be 


returned */ 


unsigned far *Action; /* pointer to the error action to be 
returned */ 


unsigned far *Locus; /* pointer to the error locus to be 
returned */ 





Compatability Mode Restriction 


None 
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Exception Handling 


An exception is generated by the 80286 CPU whenever it detects an error. These 
errors are generally a result of an internal problem with an application rather than 
a fault within the operating system (i.e., a divide overflow). Each exception is 
handled by a vector, identified by a vector number. A vector is simply a routine 
which is automatically invoked by the processor whenever the corresponding 
exception is generated. The default action taken by OS/2 when any exception 
occurs is simply to terminate the guilty process and to return error number 1811 
with a message indicating the exception vector value. OS/2 provides function Dos- 
SetVec which allows applications to replace the default OS/2 vector handling 
routines with their own. Using DosSetVec OS/2 applications can trap and handle 
certain exceptions so as to go on with their execution, instead of being terminated 
under the default action. Even if the process does not need to handle the 
exception, it still can use DosError to disable the user notification of exceptions. 

Since the user defined vector set up with DosSetVec replaces the default 
OS/2 vector, itworks in much the same way as DosSetSigHandler. We recommend 
that the programmer read Chapter 6 to fully understand the problems involved in 
signal handling, since vector handling requires the similar considerations. 

Just as with signal handling, DosSetVec requires an address identifying the new 
exception handling routine. The address of the default exception handling 
routine is returned to the process using DosSetVec. When the process no longer 
needs to trap the exception, it must use this returned address with DosSetVec to 
restore the pre-defined exception handling routine. 

Since vectors are interrupts generated by the CPU as a result of an error 
condition, vector handling routines specified by the programmer with DosSetVec 
should respond to them with great gravity. The vector handling routine should 
should recover the exception whenever possible, or clean up its resources and 
terminate the process. As in signal handling, the primary thread is also used to 
handle the vector. Therefore, the primary thread should not be used for any time- 
critical events since it might be interrupted to handle the vector. 

The 80286 generates 14 types of exceptions. Each exception is represented by 
a different vector number. Certain exceptions can only be handled by OS/2. 
Table 8.1 shows a list of all possible vectors generated by the 80286. The list is 
presented for the sake of thoroughness, since only six of these interrupts can be 
managed by the function DosSetVec. These are exceptions 0, 4, 5, 6, 7,and 16. Two 
vectors, 8 and 9, always cause the shutdown of the CPU. Vectors 1 through 5 are 
hardware interrupts handled by the Bios. Vector 11 is handled by OS/2 to 
implement virtual memory. 
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Vector Number Description Handled by 
Application 

0 Divide Error Exception. Divide by zero. Yes 

| Single Step Interrupt. Used by debugger. No 

Z NMI Interrupt No 

3 Breakpoint Interrupt No 

4 Overflow Detected Yes 

D Range Exceeded. Value exceeds limit Yes 


previously set for it. 


6 Invalid Opcode. Rarely occurs in compiled Yes 
programs. 
7 Processor Extension Not Available. Usually Yes 


occurs when a program tries to access the 
80287 coprocessor when it is not installed. 


8 Double Exception Detected. 80286 No 
will shutdown. 


2 Processor Extension Segment Overrun. No 
Usually this error is caused by the 80287. 
The CPU will shutdown. 


10 Invalid Task State Segment. No 


1] Segment Not Present No 


(continued) 
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12 Stack Segment Overrun or Not Present. No 
Stack underflow or overflow. 


13 General Protection. Invalid selector. No 


16 Processor extension error. This error Yes 


is caused by the 80287. 
Table 8.1 80286 Vectors 


DosSetVec 


DosSetVec sets up a vector handling routine which replaces the default vector 
handling routine defined by OS/2. The function requires the vector number, and 
the address of the new vector handling routine, and returns the address of the 
previous handling routine. Once a vector is generated by OS/2, control is passed 
to the vector handling routine. With the exception of vector 7, all vectors suggest 
that there is a serious error within the program. The vector handler, therefore, 
should clean up its resources and exit the program. However, if the program 
anticipates the vector (for example, the divide by zero error) it can continue its 
execution as long as it understands the cause of the error. When the program stops 
its execution, it should use the returned address of the previous handling routine 
to set the handling routine back to the system default. 

The programmer should be aware of several irregularities when installing an 
exception handler. In real-mode, the divide by zero exception places the IP one 
instruction away from the one that caused the error. In protected mode, the 80286 
and 80386 place the IP at the offending instruction. A C exception handler must 
restrict its actions to displaying a message or logging the message to STDERR, then 
exiting. If the exception handling routine needs to access registers, it must be 
written in assembler. Also, a C exception handling routine must be compiled with 
the (-Gs) flag to disable stack checking, because during an exception the contents 
of the segment registers may be corrupt. In large C programs containing multiple 
data segments a C handling routine should not manipulate the segment registers. 
If the handling routine attempts this, the main program will crash when it regains 
control. We recommend that exception handlers should be written in assembly to 
take full advantage of its capabilities. 

DosSetVec can handle six possible vector numbers. These are numbers 0, 4, 5, 
6, 7,and 16. The vector handling routine should be declared as a PASCAL FAR 
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procedure without any arguments as follows: 
void PASCAL far VectorHandler(); 


The process should determine whether a 80287 coprocessor is present before 
assigning a handler to vector number 7. When the process sets up a vector handler 
for vector number seven (7), the machine status word or MSW of this process will 
be set indicating that an 80287 coprocessor is not present. To determine the 
hardware configuration of the system it uses function DosDevConfig. When the 
process restores the handling routine for vector number 7 to the system default, 
the MSW will be changed to reflect the actual configuration of the system 
hardware. 


DosSetVec (VecNum, VectorHandler, PrevHandler) 


unsigned VecNum; /* vector number must be either 0, 4, 5, 
6, 7, 16 */ 

void PASCAL (far *) VectorHandler; /* address of the vector handling 
routine */ 

unsigned long far *PrevHandler; /* returned address of previous 


routine */ 
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Compatability Mode Restriction 


Vector number 7 cannot be handled. 


Hard Error Handling 


As explained earlier, hard errors are usually handled by OS/2. Because the user 
can often recover hard errors, it is best for the application to allow OS/2 to notify 
the user in such cases. OS/2’s handling of hard errors is not appropriate for turn- 
key or closed systems which do not have an operator, because any type of hard error 
handling requiring a user interface causes the system to wait forever. For this type 
of system, or for any programs that need to disable OS/2’s notification of the user, 
the function DosError can be used. 


DosError 


The function DosError either disables or enables the user notification of hard 
errors and/or exceptions by OS/2. ‘The default is to notify the user. DosError only 
changes the error handling status of the process that called the function; the status 
of other processes in the system remains unchanged. Itis recommended that once 
the process terminates, the user notification should be reset to the default option. 

DosError requires a bit-mask parameter (Flag) which represents the options 
specified by the process. 


DosError (Flag) 


unsigned Flag; /* hard error or exception user 
notification option */ 
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Compatibility Mode Consideration 


Under the compatibility mode, if function DosError was issued to disable hard 
error notification, or flag = 0000, any attempt to generate interrupt 24H or the 
critical handler interrupt will fail. Function DosError must be issued with Flag = 
QOO1 in order for Int 24H to run. 


Message Retrieval Facility 


The message retrieval system provided by OS/2 requires several OS/2 utilities 
to set up the message file. A program’s retrieval of these messages requires the use 
of message retrieval API functions. The messages in the message file must follow 
a certain format. The inclusion of string arguments or parameters within a message 
allows the process to add extra information to a pre-defined message as necessary. 

The necessary steps to incorporate message retrieval for a program are: 


=" Create the text file containing the messages according to a prescribed 
format. 


= Convert the source file to a message file using the utility MKMSGF. 


= Include the API message retrieval function calls within the application. Use 
DosGetMessage to retrieve a message with the option of incorporating 
variable parameters within the message. The message can also be retrieved 


'OS/2 Technical Reference refers to this as a hard error pop-up. This means that OS/2 uses function VioPopUp 
from a background process to notify the user. 


?Exception user notification is also referred to as an exception pop-up. 


Error Handling and Message Retrieval 299 


by the program and the variable parameter inserted later. This is done 
when the program is uncertain of the content of the message. In this case, 
the message can be retrieved with DosGetMessage, scanned, and the 
proper parameters inserted with DosInsMessage. ‘To output the message 
to the screen or a file, the process must use function DosPutMessage. 


The performance of a program is improved when certain frequently used 
messages are loaded into RAM along with the preloaded code and data segments. 
This is done using the MSGBIND utility. (This utility is also used to run 
applications which use external messages under DOS 3.x, or family API.) 


Message Format 


The source file for messages can have any file name but must have the extension 
“TXT.” The format of the source file is as follows: 


" A three-character line identifying the component of the application to 
which the message file belongs. 


™ Following the component line are the messages in numerical order. Each 
message contains a header and the text of the message. The format of the 
message header consists of the following components: 


Message Number. A four-digit number followed by the message type. 


Message Type®. A character which specifies the type of message. The value 
of the type character must be from among the following: 


E - Error. The message describes an error. 

H - Help. The message is a help message. 

[ - Information. The message describes some information to the user. 
Pp - Prompt. The message is a prompt to which the user must respond 


The header must be followed by a colon (:) and a space ( ). Immediately 
after the space comes the actual text of the message. 


The format of the text must follow these rules: 


# Any ASCII character can be included in the message. 


= A variable parameter can be included at any point within the text using the 


“The Microsoft OS/2 Technical Reference does not mention the Message Type feature although the JBM OS/2 
Technical Reference does. It would seem to make no difference whether the message type character is present for 
the proper handling of messages. 
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“%” followed by a number from 1 to 9 (ie., %1, %2 or %9). Using 
arguments in DosGetMessage and DosInsMessage, a program can specify 
an ASCII string to replace a parameter. These parameters permit a 
program to vary the contents of a message. 


= A special parameter, %0, is used to notify the MKMSGF utility that a 
linefeed and a return (LF/CR) should not be included at the end of the 
message. This allows the message to be used as a prompt which accepts 
information on the same line of the display. 


Once a source message file is created using an ASCII editor, a message file is 
converted from the source file using the utility MKMSGF from the command line. 
The arguments of the utility are: 


MKMSGF sourcefile message file 


Code indentifying 
application 
component 









Variable text 






Hi,[%1 |How are you? 


File %1 not found, drive %2: 


Message 
header 


Message #, 


specified by Message class 
application Fixed text 


Figure 8.1 illustrates the format of a message and the message source file. 
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The parameter sourcefile specifies the name of the source file which can be any 
name as long as it has an extension “.TXT.” The parameter message_file specifies 
the name of the message file which is created to store the messages. The message 
file name can be anything; it is given extension “.MSG” by the utility. 


Message Retrieval Functions 


Three API functions are provided to handle message retrieval from message 
files. These functions assume that the message file was properly created using the 
correct format and the utility MKMSGF. A message can be retrieved and variable 
parameters within the text replaced with appropriate messages using the function 
DosGetMessage. If the calling process does not yet have the format of the message 
string, it can still retrieve the message with DosGetMessage without substituting 
any of the parameters. This is because DosGetMessage only retrieves the message 
and does not outputit to a file or a device. Later, once the structure of the message 
and the necessary parameter values have been determined, the function DosIns- 
Message can be used to insert these values into the message. Function DosPutMes- 
sage is used to output the message to a device such as the video buffer or a file. 

All parameters should be replaced with the proper value by the process before 
the message is output to the user. Ifa message contains a parameter that has not 
been replaced, it reaches the user displaying the un-replaced parameter symbol. 
For example, if a message contains the parameter symbols %1 and %2, and only 
%1 is replaced using the API functions, when the message is displayed it will 
contain the unreplaced %2 symbol. 


DosGetMessage 


DosGetMessage retrieves a message from a system message file. When DosGet- 
Message is invoked, OS/2 always attempts first to retrieve it from the message 
segment in RAM. If the message is not available in RAM, OS/2 gets it from the 
specified system message file. The process need not be concerned about where 
OS/2 gets the message. In order to retrieve a message a process needs only know 
the path and name of the file in which its messages are stored and the message 
number desired. 

The process also has the option of inserting the values for the message 
parameters immediately with DosGetMessage, or of retrieving the message first, 
and later inserting the message parameters with the function DosInsMessage. 
OS/2 reads the message from the system file and stores it in the data buffer 
specified by DosGetMessage. The length of the message will also be returned to 
the process. 
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DosGetMessage requires the address of a target data buffer (DataArea) in which 
the retrieved message will be stored, the length of this data buffer (DataLength) , the 
message number (MsgNumber), the file name (f%leName), and the address to which 
the length of the message will be returned (MsgLength). If parameter substitutions 
are also required, the values of the parameters are stored in a data structure 
specified by /uTableand the number of parameters to be substituted is specified by 
IvCount. Ifno substitution is required, the parameter /uCowntshould be set to zero; 
OS/2 will then ignore it. 

lvTableis a pointer to an array consisting of from | to 9 double-word FAR pointer 
elements. Each of these pointers points to an ASCIIZ string which is to be 
substituted for a parameter in the message. The first ASCIIZ string represents the 
value for the first parameter (%1) and so on. If the string is a null string, OS/2 will 
not substitute it for the parameter in the message. The parameter /vCount 
represents the range of parameters to be substituted. If /uCount equals 4, this 
means that parameters 1 to 4 are going to be substituted with four values stored in 
the array pointed by /vTabdle. If IuCountis out of range, greater than 9 or less than 
0, an error 320 will be returned. 

If the process only wants to substitute parameters | and 3, the value of [uCount 
should be equal to 3, and /vTableshould point to an array containing three double- 
word FAR pointers with the second pointer to a NULL string as demonstrated by 
the following C code: 


unsigned IvCount; 

ghar “IvTaple| |: 

Letrepy (*Iviable[0],” walwe 2. \\O") 
*Ivtablell) = “\0*s 

Letreny (*Iiviable(2)],"° value 3 \\0"): 
iylount = 3; 


FileName must be a pointer to an ASCIIZ string containing the drive, path, and 
file name information of the system message file. This message file must be created 
by utility MKMSGF. 

The number of the message, MsgNumber, is the same as the four-digit number 
specified in the message header. If the process wants to retrieve message number 
1000, MsgNumber should be equal to 1000. 

OS/2 returns the content of the specified message string to the data buffer 
specified by DataArea. The length of this data buffer should be as great as the 
number of bytes returned by MsglLength. If the length of the message is smaller 
than the length of the data buffer specified by DataLength, there is no problem. If 
the message length is longer than the length of the buffer, an error is returned and 
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OS/2 puts as much of the message as it can into the the data buffer. In such cases, 
the process should use the returned message length value to allocate a larger 
buffer, and then request the message again. 

If OS/2 cannot retrieve a message due to a hard drive problem or invalid 
parameters, one of the error numbers in Table 8.2 is returned: 


Number Error Message 

316 Message is longer than the specified buffer. 
Allocate more memory to the buffer. 

317 Message ID number is not present in the message 
file. 

318 “Unable to access system message file.” ‘This 
error is probably due to a disk media error. 

oly The message file format is invalid. 

320 The /vCownt variable is out of range. 

321 System cannot perform the requested function. 

- Use DosErrorClass to determine the cause of the 

error. 


Table 8.2: Hard drive and invalid parameter error messages. 


DosGetMessage (IivTable, lvCount, DataArea, DataLength, MsgNumber, FileName, 
MsgLength) 


char far * far *IvTable; /* arrays of one to nine ASCIIZ string 
pointers containing the parameter 
values */ 

unsigned IvCount; /* range of parameter to be 
substituted */ 

char far *DataArea; /* data buffer where the message will be 
stored */ 

unsigned DataLength; /* length of the data buffer */ 

unsigned MsgNumber; /* the message number of the requested 
message */ 

char far *FileName; /* file name of the system message file */ 

unsigned far *MsgLength; /* pointer to the value of the message 


length to be returned */ 
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Compatability Mode Restriction 


None 
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DosinsMessage 


DosInsMessage is used by a process to insert strings into a message’s variable 
parameters after it has been retrieved from the message file with DosGetMessage. 
DosInsMessage does not retrieve the message from RAM or the message file, but 
merely inserts strings into the variable parameters of a message that has already 
been placed in a data buffer by DosGetMessage. This form of parameter 
substitution is useful for two reasons: If a process is not certain of the format of a 
message in the message file, it may first retrieve it with DosGetMessage. It can then 
scan the message to determine its structure and the parameters that it requires. 
Finally it can pass the appropriate parameters using DosInsMessage. In programs 
where speed is an issue, the process can retrieve all the messages in the beginning 
ofits execution, and later insert the necessary parameter values into their text. This 
eliminates the need to wait for the disk access to load the message file. 

DosInsMessage requires the address of the data buffer in which the previously 
retrieved message was stored by DosGetMessage (Msg/nput), and the address of a 
new data buffer to which the message with the replaced parameters will be output 
(DataArea). The length of the input message (Msg/nLength) and the length of the 
output data buffer (DataLength) must also be specified. If the input message length 
is longer than the length of the output buffer, an error number 320 is returned and 
OS/2 puts as much of the message as fits into the the data buffer. This should not 
be a problem, however, since the application knows the length of both the input 
and output buffers. 

The values and range of the parameters to be substituted are specified by lu7able 
and [vCount respectively. Their structure and use are discussed in the previous 
section. 


DosinsMessage (IvTable, lvCount, Msginput, MsginLength, DataArea, DataLength, 
MsgLength) 


char far * far *IvT able; /* arrays of one to nine ASCIIZ string 
pointers containing the parameter 
values */ 

unsigned IvCount; /* range of parameter to be 
substituted */ 

char far *MsgInput; /* address of the input message */ 

unsigned MsgInLength; /* length of the input message */ 

char far *DataArea; /* data buffer where the new message will 


be stored */ 
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unsigned DataLength; /* length of the data buffer */ 


unsigned far *MsgLength; /* pointer to the value of the new 
message length to be returned */ 
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Compatability Mode Restriction 


None 


DosPutMessage 


Function DosPutMessage outputs a message retrieved by DosGetMessage to a 
device handle. The handle of any file or device opened via the function DosOpen 
can be used to accept the message. If the device is the video display, OS/2 assumes 
that the screen is 80 characters wide and the starting cursor position for the 
message is column 1. Line-wrapping is used for messages longer than 80 
characters. 

Three parameters are required by DosPutMessage: the file handle, the length 
of the message, and the address of the string containing the message. OS/2 simply 
outputs the number of bytes indicated by the message length to the file handle, so 
the message does not have to be an ASCIIZ string. The file handle can be any 
currently opened file handle, including standard ones. 


DosPutMessage (FileHandle, MessageLength, MessageBuffer) 


unsigned FileHandle; /* Handle of output file or device */ 
unsigned MessageLength; /* Length of the message */ 


char far *MessageBuffer; /* Pointer to the message string */ 





308 Advanced Programmer's Guide to OS/2 





Compatability Mode Restriction 


None 


Example 
MAKE FILE-ERRMSG 


dF Makefile for MESSAGE.C and ERRMSG.MSG 


CFLAGS= -G2 -Zi -Od -Lp -Ze 
LIBS = dosealls.lib 


Srrmes.Msei errmss. Txt 
mkmsgf errmsg.txt errmsg.msg 


message.obj: message.c 
cl -e S(CFLAGS) message.c 


message.exe: message.obj 
link feo message,message,,$(LIBS),: 


MESSAGE TEXT FILE (ERRMSG.TXT) 


ERR 


ERROOOOE: Invalid Parameters #1: (%1) and #2: (%2). 


ERROOO1LH: A typical help message about %l 
ERROOO2T: The %1 %2 


ERROOO3P: This is a test message (no linefeed or Cr at the 


end) %0O 
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PROGRAM SOURCE 
/* MESSAGE.C 


This program demonstrates how to use OS/2 message retrieval 
ning ee mae a he 


An ASCII text file must be prepared containing all the messages 
and message numbers in a special format explained earlier before 
runtime. The ASCII text file must be converted to a message 
file using the utility MKMSGF. | 


This program will use API functions DosGetMessage, DosInsMes- 
sage, DosPutMessage to display the messages. 


The error file read from is ERRMSG.MSG. 
Any message file, including OS/2 error messages, file can be 


read as long as a valid error number and valid arguments to the 
error parameters are passed. 


a 


+#include “doscalls.h” 


char FileName[] = “ERRMSG.MSG”; 

char Message|[] = “Message”; /* message to insert */ 

char Message2[]= “Number”; 

main {) 

{ 
char far *T¥Table[2) ; 
unsigned IvCount : 
char DataArea[100]; 
unsigned DataLength; 
unsigned MsgNumber; 
unsigned MsgLength; 


unsigned ret; 
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printf (“\nSupposa an a@rror occur...”); 
printf(“\nRetrieving Error #1 using DosGetMessage without 
any error arguments”) ; 


Ivooume =U 
MsgNumber = 1; 
DataLengsth = LOO: 


ret = DOSGETMESSAGE ((char far * far *) IvTable, 
IvCount, 
(char far *)DataArea, 
DataLength, 
MsgNumber, 
(char far *)FileName, 
(unsigned far *)&MsgLength) ; 
if (ret) | 
printf(“\nDosGetMessage failed: %d”,ret); 
DOSEZITUT 0) = 
} 
printf(“\n\nMessage displayed: “); 


ret = DOSPUTMESSAGE (1, (* autput to Brandard cutout */ 
MsgLength, 
(char far *}DataArea) ; 


if Lret) { 
printf(“\nDosPutMessage failed: %d”,ret); 
DOSEXIT(1,0) ; 
} 
printf(“\nNotice the argument still in the string”); 
printf(“\nWe will read in another message with the inser- 
tion string”): 


IvTable[0] = (char far *)Message; 
IvTable[1] (char far *)Message2; 


[vGount= 
MsgNumber = 
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ret = DOSGETMESSAGE ((char far * far *) IvTable, 
IvGount , 
(char far *)DataArea, 
DataLength, 
MsgNumber, 
(char far *)FileName, 
(unsigned far *)&MsgLength) ; 
if (ret) { 
printf(“\nDosGetMessage failed: %d”,ret); 
DOSEXIT(1,0) ; 
pears Co eS 


ret = DOSPUTMESSAGE (1, /* gutput to etandard output */ 
MsgLleneth, 
(char far *)DataArea): 


if (ret) 
printf(“\nDosPutMessage failed: %d”,ret); 


DOSEXIT (1,0) : 


Adding Message File to RAM 


It is sometimes desirable to have some or all the messages for an application 
loaded into RAM memory at load time, along with its primary code and data 
segments. This is usually done to speed performance: to save on the access time 
to the disk, or in situations where disk access is not feasable (for example, process 
control applications). OS/2 provides the MSGBIND utility to allow programmers 
to specify a subset of messages in the message file(s) to be included in the load 
kernel of an application. The MSGBIND utility works with multiple message and 
.EXE files. These messages are kept on a special data segment, called a message 
segment, which is added to the application or dynamic link library. 

The messages bound to an application program are not removed from the mes- 
sage file. When DosGetMessage is issued, it first searches the message segment of 
the application for the requested message. If does not find it there it looks for it 
in the specified message file. 
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Format of ASCII File Used with MSGBIND 


The MSGBIND utility works in conjunction with information specified in an 
ASCII file. This ASCII file can have any extension. It contains information 
identifying the .EXE file to which the messages are to be bound, the names of the 
formatted message files from which the messages are to be taken, and the numbers 
of the messages to be included in the .EXE file. 

The format of this ASCII file is as follows: 


Identification of the target .EXE file 


>drive: path filename extension 


example: 


>c:\apps\talk\dial.exe 


Identification of the message file 
<drive: path filename.MSG 


example: 


< c:\messages\talk.msg 


The first line of the file contains the name of 
the .EXE file to which the meassages are to 
be bound, preceded by a “>” (greater than 
sign). If the file name does not include 
drive and path information, the current 
drive and directory are assumed. All mes- 
sages following this line will be bound to this 
.EXE file until the end of the message list, or 
until another file is specified with a new “>” 
line. 


The second line of the file contains the 
name of the message file, with the .MSG 
extension, from which the messages to be 
bound to the previously specified .EXE file 
are to be taken, preceded bya “<“ (less than 
sign). This file must be a valid formatted 
message file (created with MKMSGF). Ifthe 
file name does not include drive and path 
information, the current drive and direc- 
tory are assumed. All messages following 
this line are taken from this message file. It 
is possible to change the message file from 
which messages are drawn by specifying 
another .MSG file with a new “<“ line. 


Identification of the messages 
character component id 

followed by 

four digit message # 


example: 


dial0OO 
dialool 
dialdo5 


diailo29 
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The third part of the ASCII file contains 
a list identifying the messages in the mes- 
sage file to be bound to the .EXE file. Each 
message is identified by the three-character 
code identifying the application compo- 
nent to which the messages belong (see 
pages 298-299), followed by the four-digit 
message number. These message numbers 
must be specified in ascending order. 


It is possible to specify several message files from which the messages are to be 
drawn by repeating the last two steps as many times as is necessary. For example, 
the following file, when used in conjunction with the MSGBIND utility, binds the 
specified messages from the files TALK.MSG and ERROR.MSG to the application 


program DIAL.EXE. 
?\apps\talk\dial.exe 


<\messages\talk.msg 
diaQ009 

dia0015 

diaOl10l 

Ernvoo/ 

trn0O0Q08 
<\messages\error.msg 


errO0loo 
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erroiol 
errol1e? 
errOol1o03 


errog9y 


It is also possible to specify several .EXE files to which messages are to be bound 
with one ASCII file by repeating all three steps used in building the file (identifying 
the .EXE file, identifying the .MSG files, and message numbers) as many times as 
is necessary. 


Using the MSGBIND Utility — 


The MSGBIND utility requires only one argument: the drive, path, and name 
of the ASCII file whose format was discussed in the previous section. This is the 
syntax of the MSGBIND utility: 

MSGBIND drive path filename extension 


Example: 


msgbind myapp.bnd 


Chapter 9 


 . 
Linking and Dynamic Linking 





Introduction to Linking 


he linking process involves the preparation of code modules that can be 
| executed by a CPU. It involves gathering the various compiler- or assembler- 

prepared object code modules and associated data that make up an applica- 
tion into one executable module. This process is necessary because an application 
often consists of several components which are physically separated from one 
another in the address space of the computer. For example it is common to have 
an application’s main program make use of subroutines, libraries, and data that lie 
in separate files. It is also common to have applications make use of libraries 
created by a different compiler (e.g., allowing C programs to make use of routines 
in a long-standing FORTRAN engineering library). In these situations the 
program makes a call or a branch to a routine found in a different file. Such a call 
or branch is called an external call, or an external reference. The linking process 
informs the main program where to find the code or data it needs when making 
an external reference. It is said that the linking process resolves external refer- 
ences. 


Static Linking and Dynamic Linking 


Under OS/2 linking is a a far more complex issue than is the case under PC- 
DOS. Under PC-DOS linking is accomplished by combining all the object code 
files, or modules, making up an application into one large executable (.exe) file. 
This includes error and exception handling routines which might not be executed 
during most runs. When a program is invoked its entire execution module is 
loaded into the main memory. This works well, though it results in large 
executable modules. This is not a problem in a single-tasking system, but under 
OS/2 where multitasking and memory over-commitment are the norm, this 
method, called statzc linking, requires an excessive amount of memory swapping. 
For this reason OS/2 provides facilities that allow the programmer to specify only 
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Data Segment B 


Figure 9.1 (a) Before Linking (b) After Linking 


the code segments representing the most commonly used functions of a program 
to be loaded into physical memory at the start of its execution. If the other 
functions are needed during execution, their code segments can be loaded into 
memory on demand. This method of linking, where not all code segments are 
loaded into memory at the start of program execution, is called dynamic linking. 
Instead of massing together all the executable code needed by an application into 
one executable file, OS/2 implements dynamic linking by keeping track of the 
memory segments on which external routines reside, and their entry points on 
those segments. When the external routine or library is called, these segments are 
brought into memory and the control transfer accomplished. 

There is a further advantage in keeping the external routines used by an 
application in separate modules instead of physically massing them together in 
one large executable module. Under the static linking process any changes made 
in the external routines means that the entire application must be relinked from 


Linking and Dynamic Linking 317 


scratch (in order to get rid of obsolete code and include new code). Under 
dynamic linking external routines can be changed without re-linking the entire 
application. 

Needless to say, only applications written for protected mode can take advan- 
tage of dynamic linking. 


Re-Entrancy 


Under DOS, each time a program is executed, its entire executable module is 
loaded into memory. Even when two or more programs happened to share 
common object modules, multiple copies of these modules must be loaded into 
memory. OS/2, being a more sophisticated operating system, allows for the 
creation of re-entrant code segments. A re-entrant code segment is one which can 
be can be invoked simultaneously by all the processes currently running in the 
system. Therefore, multiple instances of the same process can be running using 
the same physical code segments. Different applications or processes can also 
share a common code segment. 

The programmer can specify that onlya single copy of a code segment be loaded 
into physical memory. ‘This single copy will then be shared among all the 
applications using the code, or by instances of the same application running 
simultaneously. Since it will no longer be necessary for each application using a 
library to have its own copies of the routines in physical memory, the space savings 
will be significant. 


Introduction to Dynamic Linking under 0S/2 


Dynamic linking is carried out two ways under OS/2. One resolves all the 
external references for a program before it begins execution. This is called load- 
tame linking. ‘The other method is called run-time linking. When using run-time 
dynamic linking, the external references for a program are not resolved until the 
call to the external routine is actually made. ‘To use more metaphorical language, 
we can say that when using load-time linking the program knows where to find all 
the external routines, or data segments, which it may wish to call, even if they are 
not loaded into memory when the .exe file is invoked. When using run-time 
dynamic linking, on the other hand, the program does not find out how to get to 
the external routines or data segments until the external call is made. 

The programmer can choose between these two methods, or use a combination 
of them when linking together an application. Load-time linking allows all the 
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overhead associated with the linking process to be expended once before run- 
time. This allows for fast access to external dynamic link routines because linking 
is implemented using the swapper portion of the operating system. Access to the 
external routines is slower when using run-time dynamic linking, however, be- 
cause the external references are not resolved until the external call is made. For 
these reasons programmers should implement load-time linking for frequently 
used routines and data segments. Run-time linking should be implemented for 
infrequently used code or data, or when an application needs to greatly vary the 
external routines, and data, it uses. 


Dynamic Link Library 


Load-time dynamic linking is accomplished using the OS/2 utilities LINK and 
IMPLIB. Both methods of load-time dynamic linking work with dynamic link 
modules. Dynamic link modules grant applications access to routines and data 
segments that are not physically part of their executable file. 

The LINK utility is used to create a dynamic link library (DLL) which contains one 
or more dynamic link modules. The LINK utitility is also used for linking these 
dynamic link libraries with programs to create the executable file. Even if an 
application does not utilize any programmer defined dynamic link libraries, it 
must be linked together with several OS/2 provided DLLs. 

To link together a dynamic link module, using the Linker, one specifies a list 
of object files, and a module definition file, which contains statements defining the 
attributes of the dynamic link module. Dynamic link libraries have the extension 
“dll.” 

Dynamic link libraries can also include references to other dynamic link 
libraries. ‘This is, in fact the way in which OS/2 implements the API functions. The 
main API library, DOSCALLS.DLL makes references to a number of other API 
libraries which do not have to be explicitly linked to an application. These libraries 
contain the actual code for the API functions: 


DOSCALL1.DLL - Ring 3 DOS functions (DOSXxx) | 
VIOCALLS.DLL - Video Input / Output (Vio Xxx) 
KBDCALLS.DLL - Keyboard functions (KbdXxx) 
MONCALLS.DLL - Monitor (Mon Xxx) 
MOUCALLS.DLL - Mouse calls (MouXxx) 
QUECALLS.DLL - Queue calls (Que Xxx) 
IPCCALLS.DLL - LAN manager calls (on LAN manager 


disk) 


Linking and Dynamic Linking 319 


MSG.DLL - Message Retriever (MsgXxx) 


NLS.DLL - National Language Support (NlsXxx) 


There are also other libraries that are used by the API libraries, and internally 
by OS/2: 


BKSCALLS.DLL - Base calls for keyboard subsystem 

BMSCALLS.DLL - Base calls for mouse subsystem 

BVSCALLS.DLL - Base calls for video subsystem 

ANSICALL.DLL - ANSI screen control (used by 
BVSCALLS and BKSCALLS) 

SESMGR.DLL - Session Manager (screen switching 
support) 

SPOOLCP.DLL - The spooler DLL is used for the calls 


that are shared between the spooler 
routines and the print routines. 


Import Library 


A dynamic link library contains a series of export object modules which can be 
called by other programs. From the point of view of client applications using the 
dynamic link library, these modules are import object modules as they are located 
in a DLL instead of the executable file. 

Making a dynamic link library available for use by other applications involves 
preparing its module definition file with the IMPLIB (import library) utility. This 
step produces an import library file which will be used when linking an application 
with the dynamic link library. The import library file(s) (.lib), when linked 
together with the object code of an application, provides the application with the 
entry points to the routines inside the dynamic link libraries. An example of an 
import library file is DOSCALLS.LIB. Every OS/2 application must be linked with 
it in order to use the OS/2 API calls which are located inside the OS/2 dynamic 
link libraries. 

Run-time dynamic linking, on the other hand, accesses dynamic link modules 
directly, without the need for the import library file. The figure below illustrates 
the three-step process of load-time dynamic linking, and the additional steps 
required to create a family API application. 
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Figure 9.2 (a) Linking procedure for OS/2 applications, (b) Additional 
Binding procedure for creating FAPI (real mode) applications. 


Module Definition Files 


The LINK utility is used to create dynamic link libraries and to link them with 
object code to create applications. In the former case the product of the linking 
process will be a .dll file, in the latter, an executable, .exe, file. The information 
on whether the link utility is to produce a dynamic link module or an application 
is kept in a special ASCII file called a module definition file. As in the Microsoft 
Windows environment, every application and library must include a module 
definition file, although under OS/2 module definition files for applications are 
optional. A module definition file may have any extension, but if the programmer 
does not specify one, the default extension, “.def,” is provided by OS/2. The 
module definition file contains a set of statements which define the attributes of 
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the dynamic library or application that is being linked together. 

The module definition file is more than just a utility that defines dynamic link 
libraries. With it the programmer can control attributes which greatly affect the 
performance of the application or the DLL. Before writing a large OS/2 applica- 
tion, we suggest that the programmer familiarize him or herself with the capabili- 
ties of a module definition file. 

The module definition file includes information on the name of the application 
or library, a list of imported and exported functions, the size of the program’s heap 
and stack, and the attributes of the code and data segments used by the application. 
This last feature allows the programmer to specify which segments of the applica- 
tion or library are to be preloaded, that is, loaded into memory at the start of 
execution, and which are to be loaded on demand, that is, not loaded into physical 
memory until they are called. The segment specification lines in the module 
definition file also allow certain properties of code and data segments to be 
defined, such as their access rights, privilege levels, and whether or not code 
segments will be re-entrant. 

In the next sections we will learn how to set up module definition files for both 
dynamic link modules (libraries) and execution modules (applications). We will 
also see how the segment specification lines of the module definition file allow the 
programmer to set up applications and libraries with different properties. 


Module Definition File Statements 


Table 9.1 is a list of the statements used in the module definition file. Each is 
used to specify an attribute of the library or application. 


Statement Function 

NAME Declares a module as a program, or executable 
module 

LIBRARY Declares module as a dynamic link module 
(1.e., a library module 

DESCRIPTION A one-line description of the module 

PROTMODE Declares that the application can only run in 
protected mode 

CODE Defines the default attributes for code 


segments as a group 


(continued) 
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DATA The default attributes for the data segments as 
a group 

SEGMENTS Defines attributes to individual segments 

IMPORT A list of imported functions 

EXPORT A list of exported functions 

STACKSIZE Local stack size, in bytes 

HEAPSIZE Local heap size, in bytes 

STUB Specifies a DOS 3.x executable file to be 


executed in place of the module 





Table 9.1 Module definition file statements. 


The following is a detailed account of these statements, their syntax, and their 
use: 


NAME 


Syntax: NAME [appname] 

The NAME statement identifies the executable file, created by the linker as an 
application. The presence of this statement in the module definition file tells the 
linker to create an executable file. Appnameis used to identify the application when 
importing or exporting functions. If appname is omitted then the name of the 
application is the name of the executable file created by the linker, minus the 
pathname and extension. 

If the NAME statement appears in the module definition file then the LIBRARY 
statement cannot appear. If neither the NAME statement nor the LIBRARY 
statement appears, then the linker creates an executable file by default. 

As an example, the line “NAME editor” assigns the name “editor” to the 
application being defined. 


LIBRARY 


Syntax: LIBRARY [DLLname] 

The LIBRARY statement is used to specify that the .exe file created by the linker 
is a dynamic link module. The presence of this statement in the module definition 
file tells the linker to set up a dynamic link library. If this statement appears, then 
the NAME statement cannot. If neither statement appears, then the linker creates 
an application by default. 
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The DLLname portion of the statement specifies the name that is to be used to 
identify the dynamic link module when it is referenced by a import library file or 
arun-time dynamic link call. Ifno Dilnameis specified then the name of the library 
will be the name of the .exe file created by the linker without the pathname or 
extension. 

For example, the statement “LIBRARY plotfunctions” assigns the name “plotfunc- 
tions” to the dynamic link library being defined. 


DESCRIPTION 


Syntax: DESCRIPTION ‘text’ 

The DESCRIPTION statement inserts the specified text into the application or 
library. It is useful for imbedding copyright or source control information into 
applications and libraries. The text is limited to one line. 

For example, the statement “DESCRIPTION ‘Columbia Consultants Group 
Copyright 1987’ will insert the text “Columbia Consultants Group Copyright 1987” 
into an application or library. 


PROTMODE 


Syntax PROTMODE 

If the PROTMODE statement is present in the module definition file, then the 
application or dynamic link module can only be run under OS/2 in protected 
mode. Applications/libraries which have this statement in their module definition 
file will neither run in a DOS 3.x environment nor in the compatability box. This 
is to prevent code which uses API functions that are restricted to the protected 
mode environment from being invoked in an environment in which they cannot 
run. It is possible, however, to use the STUB statement to specify the name of a 
DOS 3.x executable file which is executed when such an application or library is 
invoked. 


CODE 


Syntax: CODE [load] [shared] [execute] [privilege | 

The CODE statement defines the default attributes for the code segments of an 
application or library. The CODE statement defines attributes for all the code 
segments of an application. These attributes, however, can be overridden for 
individual segments. The CODE statement can have four possible arguments. 

The first argument, the load argument, specifies whether code segments are 
loaded into physical memory at the start of execution, or, on demand when a 
reference is made to them. Load has two possible values: 
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The second argument, shared, specifies whether unique copies of code seg- 
ments are created for each application (or each instance of an application) using 
a routine in the dynamic link library or whether the same segment in memory is 
shared by all the applications (or multiple instances of the same application) using 
the dynamic link module. This argument is used to set up re-entrant code 
segments in conjunction with certain settings in the DATA statement (discussed 
next). The shared argument also has two possible values: 





The third argument, execute, specifies whether the code segments can be read 
as wellas executed. Ifa code segmentis declared as execute only its selector cannot 
be loaded into the DS register. It is useful for keeping the contents of code 
segments private. It also has two possible values: 
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The fourth argument, privilege, is used to give code segments I/O privilege. This 
is how code segments are defined as running at privilege level 2, the IOPL, which 
allows a program to issue the IN and OUT functions to directly access hardware 
ports, and disable interrupt handling. 

This argument is either present or absent in the CODE statement. If the 
programmer wishes to assign I/O privileges to code segments, the term “IOPL” is 
included in the CODE statement. If the programmer does not wish to specify 
IOPL, this argument is omitted. Note that by using the Config.sys file, IOPL can 
be disabled for the entire system (See Chapter 19). 

For example, the following CODE statement: 


CODE LOADONCALL NONSHARED 


specifies a code segment(s) that is loaded when it is accessed, and for which a new 
copy will be loaded each time itis invoked. Because of the default values, this code 
segment(s) is readable as well as executable and has no I/O privilege. 


DATA 


Syntax: DATA [load] [instance] [shared] [write] [privilege] 

The DATA statement defines the default attributes for the data segments of an 
application or library. It defines attributes for all the data segments of an entire 
application. These default attributes, however, can be overridden on a per- 
segment basis using the SEGMENT statement. 

The DATA statement can have five possible arguments. The first is the load 
argument which specifies whether data segments are loaded into memory at the 
start of execution or on demand, when they are referenced. The loadargument for 
the DATA statement differs from the corresponding argument for the CODE 
statement in that the default value is different when the DATA statement appears 
in the module definition file. 
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The second argument, instance, describes the automatic data segment. This is 
the physical segment(s) represented by the group name DGROUP, which is the 
data segment containing the local stack and heap for an application. ‘The instance 
argument can have three values: 





The third argument, shared, argument is tied to the instance argument. The 
shared argument specifies whether all instances of an application share the same 
data segment(s) or whether a new copy is made for each: 





If only one of these arguments, instance or shared, appears in the DATA 
statement, the linker forces the values of the missing argument to match those of 
the one that is given. For example, if the instance argument is specified as SINGLE 
(solo data) and the shared argument is omitted, then data segments are automati- 
cally specified as SHARED. Conversely, specifying the shared argument as NON- 
SHARED forces an instance specification of MULTIPLE or instance data. If 
contradictory values are given for the instance and shared arguments (e.g., the 
statement DATA SINGLE NONSHARED), then ail the segments in the DGROUP 
are shared, while all others are nonshared. If the SEGMENTS statement is used 
to individually define a segment that isa member of the DGROUP with an attribute 
that conflicts with the default attributes assigned in the DATA statement, then the 
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LINKER displays a warning about the bad segment and converts it to match the 
default values declared in the DATA statement. 

The settings of the instance and shared arguments in the DATA segments have 
a great bearing on the characteristics of the module or application that will be © 
created by the LINKER. The following section demonstrates how to set up 
applications and modules with various characteristics. 

The fourth argument, write, specifies whether memory segments can be written 
to or not. It can have two values: 





The last argument, privilege, specifies whether the data segments as a whole have 
I/O privilege, (i.e., whether they will execute at IOPL, or privilege level 2). If the 
argument is specified as IOPL, then the data segments have I/O privileges. If the 
argument is omitted, they do not. Note that the Config.sys file can be set to disable 
the ability to give segments I/O privileges. (See Chapter 19.) 

As an example, the following DATA statement 


DATA LOADONCALL NONSHARED 


specifies that an application's data segments will be loaded into memory when they 
are accessed, and that data segments will not be shared among different instances 
of the application or module. By default, data segments can be written to as well 
as read; the automatic data segment is copied for each instance of the application 
or module, and the segments have no I/O privileges. 


SEGMENTS 


Syntax: SEGMENTS 
[‘]segname[‘] [CLASS [‘classname’/| [minalloc] [segflags | 
[‘]segname[‘] [CLASS [‘classname’]| [minalloc] [segflags ] 

The SEGMENTS statement is used to assign attributes to one or more segments 
in the library or application on an individual basis. The set of arguments 
represented above must be repeated for every segment whose attributes the 
programmer wishes to change. The SEGMENTS statement, itself, appears only 
once. 
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These segments are referred to by name (segname), and can be declared as 
code or data segments (classname). They are allocated a minimum number of 
bytes (mznalloc) andassigned a series of attributes (the same attributes thatwere assigned 
for the whole class of code and data statements using the CODE and DATA 
statement, except for values used for the instance argument of the data statement) 
using a sequence of segflags. ‘The attributes assigned to segments using the seg/flags 
argument of the SEGMENTS statement override the attributes set for a class of 
segments as a whole. This option is used, for example, to assign certain segments 
in an application or library to be preloaded, and others to be loaded on demand. 

The SEGMENTS statement is also used to assign an order to the segments in an 
application or a library. These segments must have already been defined by the 
compiler when an object module was created. This is because the linker assigns 
segments positions in the order in which it finds definitions for them. This 
segment order can be used when exporting a function in a dynamic link library. 

The first argument, the segname, is the name of the segment whose attributes the 
programmer wishes to change. These names are created by the compiler or 
assembler when creating object modules. Segname is optionally enclosed in a pair 
of single quotes (*). If the segname is either “CODE” or “DATA,” then it must be 
enclosed in a single pair of quotes. For example, if the name of a data segment is 
“DATA,” then the segname argument is ‘DATA’. 

Following segnamecomes the argument CLASS [‘classname’]. This is where the 
programmer specifies whether the segment being refered to is a code or data 
segment. Therefore, the value of classname can only be CODE or DATA, enclosed 
in single quotes. For example, the partial SEGMENTS statement: 


SEGMENTS 
LDATA1 CLASS ‘DATA’... 


identifies a segment named “LDATAI” as a data segment. The remainder of the 
statement can be used to change its default attributes. 

If the CLASS [‘classname’] argument is omitted, then the LINKER assumes the 
segment is a code segment. 

Minallocis simply an integer which specifies the minimum number of bytes that 
are to be allocated for the segment. If this argument is omitted, then the LINKER 
will determine the minimum allocation for the segment based on the size of the 
segment code and the size of static data used by the segment. The Minalloc value 
should be in a 16-byte paragraph boundary (or divisible by 16). 

The segflags arguments can be any combination of arguments that are valid for the 
CODE and DATA statements. There are, however, several cautions and restric- 
tions. 
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" The segflags argument must be valid for the type of segment that is being 
referred to. For example, EXECUTEREAD cannot be specified for a data 
segment. 


Values that are valid for the znstance argument of the DATA statement 
(NONE, SINGLE, MULTIPLE) cannot be used. These are used to set the 
attributes of the automatic data segment (DGROUP) only. 


As a corollary to the previous statement, if a segment that belongs to the 
automatic data group is given a sharing attribute in a SEGMENTS state- 
ment that is contrary to the attribute given it in the DATA statement, the 
linker will generate an error message and force the segment to conform to 
the specification given in the data statement. For example, in the follow- 


ing: 


DATA MULTIPLE 
SEGMENTS 
_DATA CLASS ‘DATA’ SHARED 


the segments statement will be converted to DATA CLASS DATA NON 
SHARED 


If no segflags are given, the segment is assigned the default values given in 
the DATA or CODE statement depending on its type. 


= However, if even one segflag is specified, then none of default attributes 
specified in the CODE or DATA statement apply. All the desired attributes 
for the segment must be specified again. Any attribute that is not explicitly 
specified is taken from from the following list of defaults (notice that these 
are different from the default attributes for the CODE and DATA state- 
ments): | 


NONSHARED 

LOADONCALL 
EXECUTEREAD for code 
READWRITE for data 
no LOPL 


As an example, the SEGMENTS statement 


SEGMENTS 
CS1 SHARED 
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specifies a code segment called CSI as shared. In addition, the SEGMENTS 
statement forces this segment to be load on call by default. 


IMPORTS 


Syntax: IMPORTS 
[internalname=] modulename.[entrynamelentryordinal ] 
[internalname=] modulename.[entrynamelentryordinal | 
Normally the linker uses an import library created by the IMPLIB utility to 
resolve the external references for an application or library. The IMPORTS 
statement, however, provides an alternate method for resolving external refer- 
ences from within a module. The IMPORTS keyword can be followed by any 
number of import definitions, as long as the total size of these definitions does not 
exceed 64K. Each definition must appear on a separate line. 
The internalname option specifies the name that will be used within the 
importing module to call an external function. 
Modulenameis the name of the application or library that contains the functions. 
Either one of the arguments entryname or entryordinal appears in the IMPORTS 
statement. Entryname is an ASCII string which identifies the entry point to the 
routine within the dynamic link library. Entryordinal identifies the routine by its 
ordinal position within the dynamic link library. Routines in the DOSCALLS 
library can only be called by ordinal. 
For example: 


IMPORTS INREAD=MYINOUT.1 
IMPORTS INREAD=MYINOUT.SREAD1 


Both of these statements identify a routine in the dynamic link module 
MYINOUT. The first statement identifies its entry point by ordinal (1), the second 
identifies the entry point by name (SREAD1). In both cases the routine will be 
refered to by the calling program as INREAD. 


EXPORTS 


Syntax: EXPORTS 
entryname [=internalname] [@ordinal] [RESIDENTNAME] [NODATA] 
argnum 
The EXPORTS statement is used for two purposes. It defines the routines 
within a dynamic link library or application that are to be exported to other 
programs. It can also be used to define routines that have I/O privileges. The 
EXPORTS keyword, like the SEGMENTS keyword, begins a sequence of defin1- 
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tions which define attributes on a per routine basis. The EXPORTS statement may 
be followed by a maximum of 3072 definitions, and each routine which is to be 
exported must have one. If the EXPORTS statement is used to declare an IOPL 
routine, then the routine definition contains only the entryname and iopl 
argument. 

The entryname argument defines the name which other programs will use when 
accessing an exported routine. It may optionally be followed by an equal sign (=) 
followed by the argument znternalname which is the real name of the routine. This 
is necessary should the name used for exporting the routine be different from the 
name used to reference the routine within the dynamic link library. 

The @ordinal argument defines the routine’s ordinal value within the module. 
It is an “@” symbol followed by an integer value which assigns the location of the 
function in the module’s string table. For example, a function assigned the value 
“@2” for the @ordinal argument will be the second function in that export module. 
If this option is specified, then the routine can be invoked by the calling program 
with this integer. 

The Residentname argument, either appears as such, or does not appear. It is 
used only ifan @ordinalargument is specified. When it appears it specifies that the 
function’s name must be resident at all times. This means that the name of the 
routine as well as its ordinal value will be stored in the export table of the dynamic 
link library. 

The Nodata argument also appears as such, or does not appear. If itis present 
it means that the export routine will not have its own stack or automatic data 
segment. The routine when invoked will use the caller’s stack. If the argument 
does not appear, and if the module is declared as a singledaia module, then the 
routine will use global data segment. If this is the case, and if the routine is an 
assembly language, then the first instruction in the routine must be: 


mov ax,#fds - value 


The argnum argument must be included for IOPL routines, otherwise, it is 
necessary only for routines which pass arguments. It is an integer value which 
specifies the number of parameters the routine expects to receive from the calling 
program. It works by specifying the number of words which are to be copied from 
the calling programs stack to the routine’s stack. Remember, routines that execute 
with I/O privileges are given a 512 byte stack. When declaring an IOPL routine 
only this argument and entryname can appear. 

As an example, the following EXPORTS statement defines three export 
functions, Dial, ReDial, and Beep. 
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EAPORTS 
Dial = fnel @1 6 
ReDial = fne2 @2 4 
Beep NODATA 


The first two functions, Dial and Redial, have the internal names fncl and fnc?2 
respectively. Dial is the first function in the module string table, and it expects to 
be passed six (one word) arguments; ReDial is the second function in the module 
string table, it expects to be passed four arguments. When the Beep routine is 
invoked it uses the caller’s data segment or whichever data segment happens to be 
current. 


STACKSIZE 


Syntax: STACKSIZE integer 

The STACKSIZE statement in the module definition file and the /STACK 
linker option perform the same function. Both specify the the number of bytes an 
application or library needs for its local stack. 

Asan example, the following STACKSIZE statement allocates a local stack space 
of 4096 bytes: 


STACKSIZE 4096 


HEAPSIZE — 


Syntax: HEAPSIZE integer 

The HEAPSIZE statement specifies the number of bytes in the application’s or 
libraries’ local heap. The local heap is used to allocate local memory. The local 
heap is limited to 65,536 bytes, the size of a single memory segment. If no 
HEAPSIZE statement appears in the module definition file, the default local heap 
size 1S Zero. 

The following HEAPSIZE statement allocates 8,192 bytes for the local heap: 


HEAPSIZE 8192 


There is no need to define a large heap in advance. OS/2 automatically adjusts 
the size of the heap according to a program’s needs during run-time. 


STUB 


Syntax: STUB filename 
The STUB statement specifies the name of a DOS 3.x executable file to be 
appended onto the beginning of a library or application designed to execute in 
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protected mode. Recall that libraries and applications that take advantage of 
dynamic linking and the full set of API functions can run only in protected mode. 
Modules that use only the family API subset of the function calls and that resolve 
all dynamic link routines with the BIND utility can run either in protected mode 
or in real mode. 

The STUB statement specifies the name of a program to be run in place of an 
application or library invoked in real mode when it was designed to run only in 
protected mode. This ability is useful for two reasons. Should a protected-mode- 
only application or library be invoked in real mode, a file can be specified which 
simply informs the user that the module is not executable in real mode, then 
terminates. The more ambitious programmer, however, can specify the name of 
an executable file which provides the same functions (or a reduced set of those 
functions) in the DOS 3.x environment. 

If LINK does not find this file in the current directory, it will search for it in all 
the directories specified in the PATH statement. For example, the following STUB 
statement specifies that the file instead.exe be executed instead of the protected 
mode module: 


STUB instead,.exe 


Re-entrant Code Segments 


By default, both code and data segments are specified as non-shared and pre- 
load. This means that each process will have its own code or data segments. In 
order to allow a single copy of a routine to be used by several processes, only the 
data segment for that routine should be left at the default value of nonshared. The 
attribute for the code segment should be specified as SHARED, and the attribute 
for the instance argument governing the status of the automatic data group must 
be set to either MULTIPLE, or NONE. 


Example of Module Definition File 


This module definition file specifies that the program VIOREAD.EXE runs in 
protected mode only. If the program is invoked in real mode, OS/2 executes the 
program dosstub.exe instead. 


NAME VIOREAD 

DESCRIPTION ‘Video Read Program’ 
PROTMODE 

CODE LOADONCALL SHARED 
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DATA LOADONCALL MULTIPLE NONSHARED 
STACKSIZE 8192 

HEAPSIZE 4096 

STUB DOSSTUB. EXE 


This program’s code segments are loaded on demand and a single copy can be 
shared among multiple processes (or multiple instances of the same program). Its 
data segments are also loaded on demand, but each process will have a private 
automatic data segment. Using the CODE and DATA statements described above 
will capitalize on the demand-loading and re-entrant capabilties of OS/2. No 
matter how many times you invoke the program, OS/2 will only load one copy of 
the program's executable code. In addition not all the code segments represent- 
ing the program are loaded into memory at once. Each code segment will be 
brought into memory as it is referenced. 


Linking Together Applications 


OS/2 provides facilities for linking together two types of applications. One type 
are those executed in the protected mode OS/2 environment; they may use any 
of the API functions as well as take advantage of dynamic link routines. The other 
type of applications are those which are to run in protected mode and in the 
compatability box, and DOS 3.x. The latter type of application can only use the 
family subset of API function calls and cannot take advantage of dynamic link 
routines. Because OS/2’s API functions are stored in dynamic link libraries, these 
must be bound to a family API application using the BIND utility. Recall that the 
BIND utility resolves all external references for a program in the same manner as 
in the DOS environment: by physically including the code involved in these 
references in the executable module for an application. 

In this section we will discuss the linking process for both protected mode and 
family API applications, as well as the different options available for using the 
utilities that play a part in this process, LINK, IMPLIB, and BIND. 


Linking OS/2 Applications 


The first steps in creating an OS/2 application are, naturally, writing the source 
code, and then compiling, or assembling the source code files into object code 
files. Once this has been accomplished the object code files must be linked to the 
the dynamic link libraries which they will access using the LINK utility. When 
linking together an application file an optional module definition file which 
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specifies the attributes for the code and data segments in the application may be 
specified. If the module definition file is not included when linking together the 
application, then the default attributes for the code and data segments in the 
application will be specified. 

Object code files are not directly linked to dynamic link modules (.dll files), but 
are linked through intermediary library files (.lib). The IMPLIB utility with the 
module definition file for the dynamic link library are used to produce .lib files. 
They contain the entry points for the dynamic link library. It is possible to set up 
a search path for libraries by specifying the SET LIB = path statement before 
invoking the linker, or by placing this statement in the autoexec.bat file. 

If an application does not use any programmer-defined or third party dynamic 
link libraries, then its object code modules must be linked together only with the 
file DOSCALLS.LIB. This file is the library file which contains the entry points for 
the dynamic link libraries containing OS/2’s API functions. If an application is to 
use dynamic link libraries provided by a third party, then it must be linked together 
with the provided library files as well. For example, most C applications must be 
linked with the standard run-time libraries. Ifa programmer wishes to create his 
or her own dynamic link library, then its object code files must be linked together 
to form a dynamic link module. An import library file for this dynamic link module 
must then be created for the dynamic link library using the IMPLIB utility. This 
library file can thus be used to link the dynamic link library with an application (see 
the following section). The default extension for an application produced by the 
LINK utility is .EXE, though the programmer can specify a different extension. 

There are two other methods which can be used to link an application with a 
dynamic link library. One is to use the API functions which allow an application 
to directly access a dynamic link library without going through the intermediary 
lib file. The other is to use the IMPORTS statement in the module definition file 
to directiy access the dynamic link library. 

The following files must be specified when using the LINK utility to link 
together an OS/2 application: 


# A list of the object files that make up the application. The linker expects 
a default extension of .OBJ, but the programmer can specify another 
extension. 


# A list of library (.lib) files which contain the entry points to the dynamic link 
libraries used by the application. If the application does not use any 
dynamic link libraries, it muststill be linked to the library file DOSCALLS.LIB 
which contains the entry points for the dynamic link library containing the 
API functions. 
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# An optional module definition file which is used to override the default 
attributes for code and data segments in the application. In order for the 
LINKER to produce an application module (.exe file) the module defini- 
tion file must not include a LIBRARY statement. 


Creating a Dynamic Link Library 


In order to create a dynamic link library all the source code for it must be 
compiled or assembled. Once this has been done the resulting object files must be 
linked togther using the LINK utility. When linking together a dynamic link library 
a module definition file must be included. This module definition file must 
contain the LIBRARY statement declaring the output of the linker as a dynamic 
link library. The module definition file must also include an EXPORTS statement 
listing all the functions to be exported by the dynamic link library. The dynamic 
link library produced by the linker in this fashion will have the default extension 
-DLL. 

Once a dynamic link library has been linked together, it is made available for 
use by other applications by using the IMPLIB utility on the module definition file 
for your dynamic link library. The output of the IMPLIB utility is a library (.lib) 
file which is used for linking your dynamic link library to other programs. 

If one dynamic link library makes use of other dynamic link libraries, then the 
library files for those dynamic link libraries (the .lib file produced by the IMPLIB 
utility) will also have to be specified during its linking process. If a dynamic link 
library uses any API function calls, it will have to be linked together with 
DOSCALLS.LIB. The following figure illustrates the linking procedure for 
creating dynamic link libraries, and making them available for use by applications 
and other dynamic link libraries: 

The following files are needed when linking togther a dynamic library: 


A list of the object files that make up the dynamic link library. The linker 
accepts a default extension of .obj, but the programmer can specify 
another extension. 


* A list of Library (.lib) files which contain the entry points to the other 
dynamic link libraries used by the dynamic link library being linked. Ifthe 
application does not use any dynamic link libraries, but uses API functions, 
it must be linked to the library file DOSCALLS.LIB. 


=" The module definition must be included when linking a dynamic link 
library. This module definition file must include the LIBRARY statement 
which informs the linker to create a dynamic link library (.dll) file. It is 
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recommended that the statements in this file be used to define re-entrant 
functions. 


# A inititialization routine for the dynamic link library must be included in 
one of the libraries’ object modules. This routine is discussed in the 
following section. 


The Initialization Routine 


Each dynamic link library coded in C and assembly must include a program- 
defined initialization routine. This routine corresponds to a start up routine 
automatically inserted by a compiler or assembler into every executable file. 
However, the start-up routine automatically provided by the C compiler cannot be 
used with dynamic link libraries. It must be replaced with an assembly language 
or C routine which placed in one of the libraries’ object modules. This routine 
executes the first time a dynamic link library is loaded, but not upon access by 
subsequent processes. This routine may be used to perform pre-processing for the 


LIBRARY FILES 
(created by IMPLIB, 
for any dynamic link 

libraries used by 
dynamic link library) 


DYNAMIC LINK 


(a) 
COMPILER 

| SOURCE FILES OR OBJECT FILES LINKER LIBRARY 
ASSEMBLER (.DLL FILE) 


~ MODULE 
DEFINITION FILE 
(required) 


(b) 
MODULE IMPLIB Library (.LIB) 
DEFINITION FILE UTILITY FILE 


Figure 9.3 (a) The linking procedure for creating a dynamic link library DLL 
file (b) Using the IMPLIB utility to make the entry points to the routines in the 
.DLL library available for linking with other applications. 
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dynamic link library such as variable initialization, and may call other routines. 

To include a programmer-defined initialization routine the initialization rou- 
tine automatically produced by the MS C compiler must be suppressed. This is 
done by including the following definition in any of the C modules that make up 
the dynamic link library: 


int far edecl ~acrtused () {1; 
The body of the new C initialization routine is declared like this: 


int far edecl _astart () { 
return IL: 


Notice that this routine must return a (1) to signal a successful completion. This 
is contrary to the standard OS/2 convention which requires that (0) be returned 
to signify a successful termination. 

The following is an example of an assembly language initialization routine: 


dliinit.asm 


; Dynamic link library demo module - initialization routine. 


; In this example, the initialization routine calls a dummy C 
routine merely as 
; a demonstration, since the dynamic library does not need any 


19 he ls ae On, 
TITLE a@gllinite 
.286p 
BATRN DLLINIT: FAR: C initielizgation routine 
ASSUME CS: _ TEXT 
_TEXT SEGMENT BYTE PUBLIC ‘CODE’ 
START PROC FAR 
call DLLINIT ; Calling the C intialization routine 


rev 
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START ENDP 
_TEAT ENDS 
END START 


Using the IMPLIB utitlity 


The IMPLIB utility is used to create an import library (.lib) file for a dynamic 
link library. This file is used when linking an application to a dynamic link library, 
and provides a program with pointers to the entry points of the routines in the 
dynamic link library. The IMPLIB utility requires the module definition file (used 
when creating the dynamic link library) to create the .lib file. 

The IMPLIB utility is invoked from the command line and has the form: 


IMPLIB moddeffile.[ext] libfile.[ ext] 


The extensions of the user-specified module definition file and the output 
import library file have the default extensions .def and .lib respectively. If your files 
have these extensions, then they do not have to be specified. If they have any other 
extensions, these will have to be specified. If the lzbftle parameter is omitted, then 
the IMPLIB utility will create an import library file with the same name as the 
specified module definition file, but with the extension lib. 


Creating Family API Applications 


It is possible to create applications that will run in the DOS 3.x environment, the 
OS/2 compatability box, and OS/2’s protected mode. Such programs are written 
using the Family (FAPI) subset of OS/2’s API functions. These are listed in 
Appendix B. 

The first step to take when creating a Family API application is exactly the same 
as when creating a regular OS/2 application: the source code is written and the use 
of API functions is limited to the Family API subset. The source code is compiled 
and an OS/2 executable file is created using the LINK utility. Special switches can 
be used during the linking process to create applications meant to run exclusively 
in the DOS 3.x environment. 

This creates an application that will execute in OS/2’s protected mode in the 
usual manner. In order to allow the application to execute in both the DOS 3.x 
or compatability box environment, as well as OS/2’s protected mode, this execut- 
able file must be passed through the BIND utility. The BIND utility does two things: 
first, it attaches a DOS executable header to the front of the OS/2 executable file, 
then it resolves any dynamic link calls made by the OS/2 code by replacing them 
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with the corresponding DOS or BIOS interrupt calls, or by actually including the 
the code for any extended features (not supported by the DOS INT functions) in 
the file’s DOS executable header'. This is done by providing the BIND utility with 
the name of both an OS/2 library and a real mode library file which provides the 
same functions and routine names as the dynamic link library it replaces. The 
BIND utility matches up the routines in each library and places the INT call or code 
needed to resolve any dynamic link call in the FAPI module’s executable header. 

Whenever the BIND utility is used to create an FAPI application, the dynamic 
link library file DOSCALLS.LIB must be passed to it, as well as the real mode library 
file API.LIB (which contains the DOS bindings for the FAPI dynamic link calls). 
The application developer can repeat this procedure with any other dynamic link 
library, by providing the BIND utility with both the name of an OS/2 dynamic link 
library and a real mode library that duplicates its functions. Because this code is 
actually included in the DOS executable header, an FAPI application that uses 
external libraries is usually much larger than a protected mode-only application. 
However, if a Family API application is loaded in protected mode, then the DOS 
executable header will not be loaded into memory and external references will be 
resolved dynamically. 

When using the BIND utility it is also possible to specify the names of certain 
routines in a dynamic link which will not have equivalent code bound to the DOS 
executable header. In this way Family Applications can be designed to provide 
extended functions in protected mode, but which are still executable in real mode 
without causing an error during the binding process. This process works by 
specifying a list of routine names (ora file containing a list of routine names) which 
do not have corresponding real mode code. Any references to these routines in 
real mode are mapped to an entry point called BadDynLink within the DOS 
executable header. If they are invoked in real mode, then BadDynLink returns an 
error and terminates the application. In the section on run-time dynamic linking 
we will learn how an application can use the function DosGetMachineCode to 
determine whether itis running in real or protected mode, and thereby determine 
which external calls are valid for it. 


Using the BIND Utility 


The BIND utility is used to tranform an OS/2 protected mode executable file 
into a Family API executable file. The BIND utility makes use of the LINK utility 





' See appendix B for a list of correspondences between OS/2 API functions and DOS and BIOS 
interrupts. Ifa FAPI function does not have a corresponding DOS interrupt then the code that pro- 
vides its function is included in the executable header. 
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so you will have to have a path set to the directory containing LINK.EXE. Also the 
BIND utility can only be executed in protected mode. 
The BIND utility is invoked from the command line, accepts seven parameters, 


and has the following form: 


BIND executable [libraries] [objectfile] [ /o[ executable_des | 


[/m[mapfile] [/[@ name] 


The meaning of each parameter for the BIND utility is as follows: 


executable 


libraries 


object file 


/o executable_des 


/m mapfile 


The name of the OS/2 executable file, option- 
ally including drive and path specification, 
prepared with the LINKER. 


Used to specify the list of file names, including 
drive, path, and extension, separated with a 
space. This list consists of OS/2 import library 
files and real mode library files which duplicate 
the functions of the dynamic link libraries they 
replace. Any routines in the dynamic link 
libraries which do not have a corresponding 
real mode routine must be specified in the 
name parameter. The two files 
DOSCALLS.LIB and API.LIB must always be 
specified. 


Any other object files included with the appli- 
cation which are to execute in real or compata- 
bility box mode. These filename specifications 
can also include a drive and path name, and 
must be separated from each other by a space. 


The switch “/o” is followed by a space and the 
name of the FAPI executable file to be created 
by the BIND utility. It may also include a drive 
and path specification. If this switch is omit- 
ted, then the output of the BIND utility is sent 
to the file specified by the executable parame- 
ter, 


The switch “/m” specifies that a link map for 
the DOS mode portion of the executable file is 
to be created. Ifa filename follows this switch, 
including drive and path specifications, then 
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this is the output file for the link map. If no 
filename follows the “/m” switch, then the link 
map will be output to the executable filename 
specified by executable_des or executable, with 
the extension “.bm”. 


/n name The switch “/n” specifies that a list of dynamic 
link routines follows. Each routine must be 
separated from the next with a space. These 
routines will be mapped to the BadDynLink 
entrypoint for real mode execution. This 
option allows the programmer to define 
routines that are callable in protected mode 
but not in real mode without causing a binding 
error. Ifa full filename specification preceded 
by “@” appears instead, then this is the name 
of an ASCII file containing a list of routines to 
be mapped to the BadDynLink entrypoint. 


The LINK Utility 


The LINK utility is used to prepare an OS/2 executable file or dynamic link 
library. It accepts as input a list of object files, import library (.lib) files, a module 
definition file, and a list of switches. The module definition file discussed earlier 
allows the programmer to change the default attributes for the code and data 
segments that make up a program or dynamic link library. Many of the switches 
for the LINKER allow the programmer to specify how these segments (which are 
often less than 64K) will be copied to the executable file. These switches are 
important because they can be used to tell the LINKER to arrange these segments 
in memory in a manner that can significantly increase program performance. 
Another category of switches duplicates some of the functions of statements in the 
module definition file. These are used when a module definition file is not 
included in the linking procedure. A third category of switches is used to organize 
code and data segments in ways that are compatible in special ways with the DOS 
3.x environment. We will discuss each group of switches later in this section, but 
first we will present a general discussion of the operation of the LINKER. 
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Operation of the LINKER 


The LINKER not only resolves all external references made by the various 
object modules of a program, but also has the ability to change the order of these 
segments in the executable file (1.e., to combine separate segments into one larger 
segment, and to allow non-contiguous segments of a mixed type to be addressed 
as if they belonged to the same physical segment). 

Normally the LINKER copies segments to the executable file in the order in 
which it meets them in the object files. If the linker finds two or more segments 
with the same class name (e.g., “code” or “data”) and the same class type, these 
segments will be written to the executable file in contiguous blocks. 

If the LINKER finds two or more segments with the same segment name, it will 
write them as contiguous segments in storage. This means that they can be 
addressed with an offset from the same selector or frame address. This is called 
combining segments. Combining segments allows code to share the same resources 
even though they are compiled separately. This operation will work, even if each 
segment has a different alignment type, because it is preserved by the LINKER 
when combining segments. If the LINKER attempts to combine segments that are 
greater than 64K, an error will be returned. 

Whether or not a segment will be combined with other segments depends on 
its combine type. ‘The combine type for a segment is specified when the segment is 
declared in the program. OS/2 admits the following combine types: 


public This type of segment is combined with any 
other segments bearing the same name and 
class (e.g., “code “). Several shorter public 
segments are combined together to form one 
larger one, up to 64K. 


stack This type of segment is combined with any 
other stack segments bearing the same name. 
LINK copies a stack-pointer value to the 
executable file. The stack-pointer is an offset 
to the first stack segment or combined stack 
segment LINK finds. If stack segments are de- 
clared as type stack, there is no need to give 
instructions to load these segments into the SS 
register. 
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common Common type segments are combined with 
other common type segments bearing the 
same name. When combining common type 
segments, LINK lays all the common type 
segments on top of one another creating a 
single segment that has a length equal to the 
longest individual segment. 


private This is the default combine type assigned to 
segments which do not have a definition. 
Private segments are not combined with any 
others. 


The LINKER also supports the growp concept, which allows a program to 
address segments of various classes (which are normally loaded in the order in 
which they appear, or by class) as part of the same physical segment. Access to the 
segments belonging to a group is speeded up because they are addressed with the 
same selector. The LINKER limits the number of groups which can be opened by 
a module to 20—actually 21 counting the automatic data group created by OS/2. 
A segment cannot be declared a member of two groups and the length of all the 
segments making up a group must be less than 64K. We will not discuss how to 
implement the group concept in this book since this is implemented differently 
depending on the language’®. 


Types of References Resolved by the LINKER 


The LINKER first passes through a program and determines the starting 
addresses of every segment, establishing all the segment combinations and groups 
(see the earlier discussion). Once the LINKER has done this, it computes values 
that resolve all the references made in the program. 

If the program specifies an incorrect value in a reference instruction, the 
LINKER will issue a fix-up overflow error message. Itis then up to the programmer 
to correct the problem in his or her source code. For example, if a program 
attempted to use a 16-bit offset to address an instruction in a different physical 
segment (a different frame address), a fix-up overflow error would be generated. 
Such an error is also generated if a group of segments is defined that is larger than 
64K. 


* The information will be found in the IBM Macro Assembler/2 Language Reference book. 
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The LINKER resolves four types of references: 


# Short 

= Near self-relative 

=" Near segment relative 
= Long 


A short reference is created by a JMP instruction that passes control to an 
instruction within the same segment, or group as the calling instruction. Inashort 
reference the target instruction must be within 128 bytes of the calling instruction. 
The LINKER computes a signed 8-bit number to resolve such a reference. If the 
target segment is farther away than 128 bytes, or lies within another segment or 
group, a fix-up overflow error is generated. 

A near self-relative reference targets data in the same segment or group, but 
farther than 128 bytes away. The LINKER computes a 16-bit offset for a near self- 
relative reference. A fix-up overflow error is generated by the LINKER if the data 
resides in a different segment or group. 

A near segment-relative reference involves a call to a location governed by a 
selector, that is within a physical segment, but not necessarily within the a single 
defined segment, or group. The LINKER computes a 16-bit offset for such a 
reference, and returns a fix-up overflow error if this offset is greater than 64K bytes 
or less than 0 bytes. 

A long reference occurs when a CALL instruction tries to transfer control to an 
instruction in another segment or group. The LINKER computes a 16-bit frame 
address (or selector), and a 16-bit offset to resolve a long reference. If this offset 
is greater than 64K or 0 bytes a fix-up overflow error is generated. 


The Map File 


The map file lists the name, load addresses, and lengths of all the segments that 
appear in a program. It also lists the name and load address of any groups and 
contains the program's start address and messages that report on any errors 
encountered during the linking process. 

The segment information is listed in order of ascending load address and has 
the following format: The first column contains the address of the first byte in the 
segment in the form segment number:offset, where segment number refers to an 
index on the segment table of the executable file (beginning with 1), and index 
is the distance in bytes of each segment from the beginning of a physical segment. 
The length of each segment in bytes appears in the second column, the name of 
the segment in the third column, and its class in the fourth. 
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For example, the following is the MAP file that is generated when the dynamic 
link library included in this chapter is linked: 


DLL 

Start Length Name Class 
0001:0000 OOO00H _DATA FAR_DATA 
0001:0000 OO0O00H _BBS FAR_DATA 
0001:0000 OQOOO0H CONST FAR_DATA 
0001:0000 OOOAAH _TEXT CODE 
0002:0000 00002H _DATA DATA 
0002:0002 OO000H CONST CONST 
0002:0002 OOO00H _BSSs Bos 


Origin Group 
000230 DGROUP 


Address EXport Alias 
VOOLSO050 lerrepy lstrepy 
0001:0011 Ilstrlen lstrlen 


Program entry point at 0001:00A4 


The group information tells on which physical segment in the segment table a 
group lies. ‘The program entry point, in the form segment number:offset, appears at 
the bottom of the MAP file. 

If the /MAP option was specified during the linking process, then the map file 
will also contain a listing of all the symbols (all the routine names) used in the 
program first in alphabetical order, and then in load address order. All external 
routines will have the address 0000:0000. 


LINKER Switches 


LINKER switches allow the programmer to specify which linking options will be 
disabled and which will be enabled during the linking process. These switches have 
been divided into three groups: those that should be used for programs in 
OS/2’s protected mode environment; those that are to execute in the DOS 3.x, or 
OS/2 compatability box environment; and those that can be used in both environ- 
ments. 

In all three cases LINKER switches are entered after any file name during the 
linking process in the format \switch:[argument]. If a switch requires that a 
numerical value be specified, this may be done in either decimal, hexadecimal, or 
octal following the standard C conventions: 
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Decimal Any number that begins with a digit other than 
“0.” 
Hexadecimal Any number that must begin with “Ox” which can 


contain the digits 0-9, and the letters A-F. 


Octal Any number that begins with “0” and contains 
only the digits 0-7. 


Three useful LINKER switches which may always be used are \HELP, \INFOR- 
MATION, and\PAUSE. Invoking the LINKER as LINK\H from the command line 
will print outa list of LINKER switches. Specifying the switch\,, at any time during 
the linking process will display information about the linking process on the screen 
as it is being carried out. This includes information about which module is being 
processed, and the current phase of the linking process. If the \PAU switch is 
specified, the LINKER will inform the user when it is about to write the .exe file to 
the disk. This gives the user a chance to switch disks, if the .exe file is to be written 
to a removable disk drive. 

Tables 9.2, 9.3, and 9.4 follow, listing the LINKER switches by the environment 
in which the resultant executable file is to run. The full name is presented in the 
left column. The shortest possible abbreviation for the switch is contained in 
parentheses. The second column contains the default value for the switch (this will 
be either a numerical or toggle value). The third column contains an explanation 
of the switch’s function. 


Switch Default Meaning 


\(A) LIGNMENT: number B12 Aligning a segment means 
adjusting its address to fall on 
a specific value based on the 
alignment factor (specified by 
the number argument). The 
starting address of each seg- 
ment will then be evenly 
divisible by the alignment 
factor. The alignment factor 
must be a power of 2. 


\(F)ARCALLTRANSLATION Off This option instructs the 
LINKER to translate any intra- 


(continued) 


348 Advanced Programmer's Guide to OS/2 


\(NO)FARCALL On 


\(NOP) ACKCODE Off 


\(PAC) KCODE:|[packlimit] On 


Table 9.2 Protected Mode Only Switches 


segment FAR calls into near 
calls. Using this option results 
in significant savings in execut- 
able module size and load 
time for most medium and 
large model programs. How- 
ever, there is a bug: there isa 
small chance that the LINKER 
will mistake a byte with the 
value of 0x9a as a FAR call 
instead of the constant that it 
is. ‘Take care when using this 
option. 


Intra-segment FAR calls 

TRANSLATION 

remain FAR calls. This is the 
default. 


Instructs the LINKER to 
disable the packing of neigh- 
boring code segments. See the 
next table entry. 


Instructs the LINKER to pack 
neighboring code segments 
onto the same physical seg- 
ment. The optional packlimit 
argument is used to specify the 
limit at which the LINKER 
should stop packing. If pack- 
limit is not specified, LINK 
uses 64K or the size of a 
physical segment. 


Switch 
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Default Meaning 


\(CP) ARMAXALLOC: number 65535 


\(DS) ALLOCATE 


\(E) XEPACK 


para- 


graphs 


Low 


Off 


This option allows the pro 
grammer to change the value 
of the MAXALLOC field in the 
program’s EXE header (this 
field is located at offset OCH in 
the header). The programmer 
can specify the maximum 
number of paragraphs set 
aside in storage for a program. 
This value can be varied from 

1 to 65535, a value of reserved 
storage of 16 bytes to 640K 
bytes. 


This switch works as a toggle. 
If it is absent, the LINKER 
loads data into the data seg- 
ment from the lowest address 
to the highest. If it appears, 
then the LINKER loads the 
data from the the high end of 
the data segment. 


This switch instructs the 
LINKER to remove any se- 
quences of repeated bytes 
(such as nulls), and to opti- 
mize the load-time relocation 
table before the DOS execut- 
able file. Files linked with this 
option are usually smaller and 
load faster than those linked 
without it. Unfortunately 
programs linked with this 
option cannot be used with 


(continued) 
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symbolic debuggers. For this 
reason the \CODEVIEW, 
option cannot be used when 
this option is used. 


\(HI) GH Off This option loads the file as 
high as possible in storage 
without overwriting the tran- 
sient portion of 
COMMAND.COM. It should 
be used in conjunction with 
the \DSALLOCATE switch. 
This option should not be 
used with C programs. 


\(NOG)ROUPASSOCIATION — Off This option maintains com- 
patability with previous ver- 
sions of the LINKER. It 
should not be used with C pro- 


grams. 
\(O) VERLAYINTERRUPT: 3FH The default DOS interrupt 
number number for passing control to 


an overlay is 3FH. This switch 
allows a new interrupt num- 
ber. The number parameter 
can be any decimal value from 
0 to 255, octal value from 0 to 
~377, or hexadecimal value 
from 0 to OxFF. IBM does not 
recommend using values that 
conflict with established DOS 
interrupts. 


Table 9.3 DOS or Compatability Box Mode Only Switches 
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Switch _ Default Meaning 


\(CO) DEVIEW Off Instructs the LINKER to 
include symbolic debugging 
information for CodeView in 
the output executable file. 


This option cannot be used 
with the \EXECPACK switch. 


\(DO)SSEG Off? This overrides the standard 
conventions for segment 
ordering (pages 342-344) ac- 
cording to the following rules: 
1. All segments with a class 
name ending in CODE. 

2. All other segments not in 
the DGROUP. 

3. Segments in the DGROUP 
in the following order: 

a. segments of the class 
BEGDATA 

b. any segments not of class- 
BEGDATA, BSS, or STACK. 

c. Segments of the class BSS. 

d. Segments of the class 
STACK.In addition, this 
option inserts 16-bytes of 
nulls in front of any seg- 
ment named TEXT for C 
runtime library support. 


\(H) ELP Off This switch displays a list of 
available linking options on 
the screen. Filenames cannot 
be included when specifying 
this option. 


(continued) 


3 The default is on for any program linked with the standard IBM C runtime library. 
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\(1) NFORMATION Off When this switch is specified 
information on the linking 
process is displayed on the 
screen. 


\(LI) NENUMBERS Off This option causes the 
LINKER to copy line number 
information from the source 
file to the map file. This 
option makes it easier to 
debug high level languages 
that support line numbers. If 
no map file is specified, the 
inclusion of this switch forces 
the creation of a map file with 
the name of the first object file 
encountered and the exten- 
sion .Map. 


\(M.) AP: number number= This option instructs the 
2048 LINKER to copy a list of all 

public symbols declared in a 
program to the map file. The 
number parameter specifies the 
maximum number of public 
symbols that the LINKER will 
write to the map file (see pages 
345-346). The inclusion of 
this option also forces the the 
LINKER to create a map file 
with the name of the first 
object file encountered and 
the extension .map, if no map 
file is specified. 


\(NOD) EFAULTLIBRARY Off This option directs the 

SEARCH LINKER to ignore the names 
of any external libraries found 
in an object file. Some compil- 


(continued) 


\(NOI) GNORECASE 


\(PAU) SE 


\(ST) ACK number 


\(SE)GMENTS number 


Off 


Off 


varies 


128 
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ers may include a set of default 
libraries to be linked to a 
program. This option allows 
the programmer full control 
over the libraries that are to be 
linked to the application. 


This option causes the 
LINKER to process uppercase 
and lowercase letters in symbol 
names as separate entities. 
Normally the LINKER makes 
no distinction between upper- 
case and lowercase characters. 


This option instructs the 
LINKER to pause before 
writing the .exe file so that the 
user can change disks. The 
LINKER displays a prompt. 


If this switch appears followed 
by a numerical value whose 
integer range is 1 to 65535, 
then the LINKER sets the 
application’s stack size to that 
number. This switch dupli- 
cates the function of the 
STACKSIZE statement in the 
module definition file (see 
page 332) .If this switch does 
not appear the LINKER 
calculates the size of the stack 
used by the program from the 
size of any stack segments 
specified in the object files. 


Allows the program to vary the 
ceiling on the number of 


(continued) 
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Table 9.4 Mixed Mode Switches 


LINKER Limitations 


segments per program that the 
LINKER can process. The 
number must be between the 
integer values of 1 and 3072. 
If the LINKER attempts to 
process a program which has 
more segments than this 
ceiling, an error message is 
displayed and the linking 
process is terminated.\ 


The LINK utility places limits on the programmer with regard to several 
parameters. These limits are summarized in Table 9.5: 


Item 





Symbol Table 


Load-time relocations 


Public Symbols 


External symbols per module 


Groups 


Limit 
256K 


Default is 32K. If /EXEPACK is 
used, (for OS/2 programs) the 


maximum is 512K. 


A range between 7700 and 8700 can 
be used as a guideline for the maxi- 
mum number of public symbols 
allowed; the actual number depends 
on the program. 


1023 


The programmer can define a maxi- 
mum of 20 groups. An additional 
group, the DGROUP, is always 
defined by the LINKER. 


(continued) 
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Overlays 63 


Segments 128 is the default value, but the 
maximum can be set as high as 3072 
using the /SEGMENTS option of the 


LINK command. 
Libraries 32 
Stack 64K 


Table 9.5 LINK Utility limits 


Using the LINK Utility 


There are three ways of supplying the LINK utility with the information it 
requires to link together an application or dynamic link library. The first is to 
respond to a series of prompts produced by the LINK utility. The second is to type 
the input on the command line as you would with any DOS utility. The third is to 
create an automatic response file (ARF) —a text file which contains all the responses 
given to the LINKER using method one. 


LINKING with Prompts 
When using this method to link files the programmer simply responds to a series 
of prompts generated by the LINKER. To invoke the LINKER in this mode, enter 
LINK from the command line. The LINKER presents the following series of 
prompts: 
a. Object Modules[.OBJ]: The list of object files to be linked 
together. 


b. Run Filél. EXE] : The name of the executable file to be 
created by the LINKER. 


c. List File[NULL.MAP]: The name of the mapfile to be created 
by the LINKER. 


d. Libraries[.LIB]: A list of import library files to which the 
executable module is to be linked. 
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e. Definitions: File The name of the module definition file, 

[NULL. DEF] : which is mandatory when linking a dy- 
namic link library, and optional when 
linking an application. 


For all prompts, the default filename extension is contained within brackets. 
Default extensions, may be omited. The default filename extension can be 
overridden by specifying a different one. 

Two of the prompts, one for object files (a), and the other for library files (d), 
can accept lists of file names. These are entered by placing a space ( ), or a plus 
sign (+), between the file names. If there are more file names to be entered than 
will fit on one line, the programmer can enter a plus sign (+) as the last character 
on a line and hit the Return key. The prompt Object Modules[.OBJ]: or 
Libraries[.LIB]: will reappear. 

If any specified filename does not reside in the current working directory, a disk 
and/or path specification must be made for it. Ifno path specification is given, the 
LINKER will search for the file in the directories specified by the path environment 
string if it is an object file, and in the Set Lib= path statement if it is an import 
library. If the LINKER cannot find a particular file, it re-prompts for the corrected 
information. 

For any prompt for which no information is to be specified Return may be 
entered. The only prompt to which a file name response is required is the first one, 
the Object Module|[.OBJ]: prompt (and the Definitions File[ NULL.DEF]: prompt, 
if a dynamic link library is being linked). If no response is given to the Run 
File[.EXE]: prompt, the executable file takes the name of the first file entered in 
response to the Object Module[.OBJ]: prompt and the extension .EXE. This file 
is placed in the current working directory. Alternately, if a Run File is specified, 
a path specification may also be specified which will instruct the LINKER to write 
the Run File to a particular directory. If the Map File[NULL.MAP] is not specified, 
then the LINKER will not create a map file. 

Any recognized LINKER switches may be entered after a file name in the 
format: \switch. Entering Cntrl-Break at any point terminates the linking process. 


LINKING From the Command Line 


The programmer may alternately choose to enter the LINKER information 
from the command line. In this case all the parameters are entered at once in the 
format: 


LINK ObjFiles[.OBJ] ,ExeFile|.EXE] ,MapFile|.MAP], 
LibFile|.LIB),DefFile|. DEF] 
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These parameters have the same order and value as those used when respond- 
ing to the LINKER prompts in the previous section. The same defaults are also in 
effect. The meaning of each parameter is as follows: 


ObjFIles[.OBJ] 


ExeFile|[.EXE] 


MapFile|NULL.MAP] 


LibFiles|.LIB| 


DefFrile| DEF] 


A list of object files, optionally including 
drive and path specification, separated by 
a plus sign (+) or a space. The default 
extension is .obj (which need not be 
specified), but any other extension may 
be substituted. 


The name of the run file to be output by 
the LINKER, including an optional drive 
and path specification. If this parameter 
is not specified, the LINKER creates an 
executable file having the name of the 
first file specified for the ObjFiles parame- 
ter, and the extension .exe. This file is 
written to the current working directory. 


The name of the map file to be created by 
the LINKER including an optional drive 
and path specification, telling the 
LINKER which directory to write the map 
file to. The default extension is .map 


(which need not be specified), but any 


other may be substituted. If this parame- 
ter 1s omitted, no map file is created. 


A list of import library files, optionally 
including drive and path specification, 
separated by a plus sign (+) or a space. 
The default extension is .lib (which need 
not be specified), but any other may be 
substituted. 


The name of a module definition file, 
including optional drive and path specifi- 
cation, which must be included when 
linking a dynamic link library. This is 
optionally included when linking an 
application. The default extension is .def 
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(which need not be specified), but any 
other may be substituted. 


Each parameter, whether an individual file or list of files, is separated from the 
next with a comma. LINKER switches can be specified after any parameter using 
the format \switch. Ifa parameter is to be omitted, then a comma is inserted in its 
place (unless it is the last parameter). ‘To respond with the default parameter for 
the remainder of the command line, a semi-colon (;) isentered. For example, the 
following LINK command does not include a specification for an Exefile. An .exe 
file will be created by the LINKER having the name of the first object file specified 
in the OdjFiles list, sdample.exe, in the current directory. No module definition file 
is specified. 


LINK samplét+samplelt+sample2,,alist,\lib\slib \NOD; 


In this case, all specified files have the default extension and reside in the 
current working directory except for the import library file, which resides in the 
\libr directory of the current drive. The switch after the library file parameter 
specifies that the LINKER will not search any of the default libraries specified in 
the object files (see page 354). 


LINKING With the Automatic Response File (ARF) 


The Automatic Response File contains the responses to the LINKER prompts 
described on page 41. Itis a text file and may have any name and extension. Here 
is an example: 


sample+samplel+sample2/PAUSE 
go.exe 

mapgo 

\lab \desealletslip 


To LINK using an Automatic Response File, one enters the following from the 
command line: 


LINK @[d] [path] filename[.ext] 


The @ symbol notifies the LINKER that it is to look to an ARF for the linking 
information. 
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Example of a Dynamic Link Library 


What follows is all the information necessary to construct the dynamic link 
library accessed by the remainder of the example programs in this chapter. The C 
source code for the dynamic link library routines is included below. The source 
code for the assembly language initialization routine is found in the section 
describing initialization routines. The makefile included below contains all the 
information needed to compile and assemble the source code modules, and link 
them together along with the module definition file (included) to form the 
dynamic link library. 


MakeFile for dil.dli and dil.lib 


Compiler flags should include -Au included in order to switch 
on DS and SS 
#checking. When this flag is included the compiler saves the DS 
register 

flupon function entry, loads the DS with the named data segment, 
then 

restores the DS with its previous contents upon function 

termination. 


#The -Zi flag should be included for use with CodeView 


CELAGS=-Aeni «421 -Lp -G2e -Od 
LiBS — doscalls.lib dilil.iib 


dilinit.obj.s dllinit.asm ffInformation for assembling the 
masm dllinit.asm assembly 
flanguage initialization routine. 


dlkeepis dldl,< #Information for compiling the C 
el #¢ SICFLAGS) dil.c source code 
fFfor the DLL 


dii.dii: dil.veb; #Linking info for the dynamic link 
library. 
link sco dil+dillinit,dll.dil,,descalls.1lib, dil.detf 
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gli, tips gid vaet # Creating the import library 
Limolib diil.tlab dil.der file 


Source Code- dlli.c 


f* DLC 


The initialization routine for this dynamic link library is an 
assembly routine called init.asm. Its source code is in a 
different module. 


This dynamic link library makes available to functions: 
- Istrepy and letrien. 
These functions copy 
a far-ASCIIZ string to another, and determine the length 
of a far-ASCIIZ string, respectively. 


| 

int far cdecl _aAcrriged (J) (}3 /* disable the compiler 
initialization routine */ 

int far pascal dllinit{) /* dynamic link library written 


in CG ys 
{ 
/* here te where all the initialization can be dene */ 
/* thie procedure will bea called by the atart-up */ 
/* assembly routine */ 


unsigned far pascal lstrlen(s) /* determine the lenth of a */ 
chnae far *s3 (/* Tar string */ 
/* similar to sirlen() *7 


iit 
cher tar “rs 
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t= s 
1 = 12 
while (*st+ [="\0') 


Tr ¢ 
return (i): 


ywoid far pastal letrepy(t,¢s) /* @opy to far string */ 
¢har Dar *r: /* gimilar to strepy() */ 
ehar Tar *e: 


{ 
ehar tar’ "tl: 
Char tar "ei: 


i) = 

gl. = e: 

white (*81 t= "4075 
(tela = Fe lter) s 

eS ON 


Module Definition File-dil.def 


LIBRARY DLL ;tell the linker that the program 
sis a DLL 
PROTMODE ;run only in protected mode 


DESCRIPTION ‘FAR STRING DLL’;This string will be imbedded into 
sthe dynamic library file 


DATA SHARED; make the default to share data segments 
SEGMENTS 


_DATA CLASS ‘FAR_DATA’ NONSHARED 
_BBS CLASS ‘FAR_DATA’ NONSHARED 
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CONST CLASS ‘FAR_DATA’ NONSHARED 


EXPORTS ;Exports routines. 
istrien @1 1 
Istrcepy @2 2 


Load-time Dynamic Linking Examples 


The following examples demonstrate two methods for load-time dynamic link- 
ing. The first links C code to the dynamic link library, dll.dll, through the import 
library file, dll.lib. ‘The second links this same C code to the dynamic link library 
through a module definition file containing an IMPORTS statement. 


Linking Through Import Library File 


The executable file testdll.exe is linked together with the import library file, 
dll.lib, allowing it to access the routines in the dynamic link library, dll.dll. The 
import library file must be stored in the directory which is pointed to by the 
environment variable LIBPATH, otherwise OS/2 will not be able to locate it. This 
is the preferred method for implementing load-time dynamic linking. 


MakeFile for testdll.exe 
testdll.obj: testdll.c #Compilation Information 
al -c¢ -4i -Lp -G2e -Od tastdli.« 


bestdll.exe: testdall.ob7 #Linking Information 
link jco testdll,testdll,,S Liss): 


Source Code for testdll.c 


{* FESTOLE€ 


This program accesses two functions whose entry points are 
contained in the import library file, dll.lib, and whose code 
résides in the dynamic link library DLL.DLL: 

- Lstrepy and Letrien. 
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These functions copy a far-ASCIIZ string to another, and deter- 
mine the length of a far-ASCIIZ string, respectively. 


This program defines a prototype for the functions that is 
Sinilar to the standard O8/2 API. 

The object code of the program is then linked with the import 
library which defines these dll functions or through a module 
definition file containing an IMPORTS statement. 


oe i 
Hinelude “dll.h* /* grotetypes for the dll functions */ 


main() 
{ 
char s[80]; 


lgtrepy( (char far *)s, (char far *)"Thieg is a test of DLL 
cali”): 


printe("\nStrine: Me and length; “wd, 
ae 
letrlen((char far *)s)): 


Linking Through IMPORTS Statement 


Here the source code for the previous example is linked together with the 
module definition file testdll.def. This module definition file contains an IM- 
PORTS statement which makes available the routines in the dll.dll dynamic link 
library. 


MakeFile for testdll2.exe 


testdll2.exe: testdll.obj #Linking Information 
link /cotestdll,testd112,,dosealls.1iib,testdii.detf 
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Module definition file-testdll.def 


NAME THESBTDLLZ 
DESCRIPTION ‘Demonstration def file using the import feature’ 
PROTMODE; protected mode only 


IMPORTS 
DLL.LSTRCPY ;defines the import Dll routines 
DLL.LSTRLEN 


implementing Run-time Dynamic Linking 


When using run-time linking the programmers’ object code modules do not 
have to be linked with any dynamic link libraries. This is because programs using 
run-time linking to access external routines do not reference them with a symbolic 
name, but with a full address (selector:offset combination). Any dynamic link 
libraries accessed exclusively through run-time linking procedure do not need a 
library (.lib) file prepared by the IMPLIB utility. However, any dynamic link calls 
made in the normal manner will have to be linked to their respective libraries 
through the normal linking process. 

Run-time dynamic linking is implemented through a set of API functions. 
These functions allow an application to gain direct access to a number of dynamic 
link libraries, to call routines within these modules using a full destination address, 
and to give up access to these modules when it is finished with them. This last 
feature is provided because, even though dynamic link libraries are not considered 
serially reusable resources, OS/2 does keep count of how many applications are 
currently using each dynamic link library. When this count reaches 0 (1.e., when 
no applications are using a dynamic link library) its memory segments are removed 
from physical memory. 

In order for an application to make use of run-time dynamic linking (i.e., to get 
the module handle for a dynamic link library) , it needs to know two things: the full 
file name (including drive and path specification) of the dynamic link library that 
it wishes to load and access, and the names, or ordinal values, of the functions 
exported by the dynamic link library. The names of the functions are found in the 
EXPORTS statement of the dynamic link libraries’ module definition file. The 
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ordinal value of a function represents its position within the symbol table of the 
dynamic link library: it is specified by the order of the exports statements. 

In order to open a dynamic link library for access, an application issues the 
function DosLoadModule which loads the dynamic link module into memory* and 
returns a module handle. Because it is quite likely that the needed dynamic link 
library has already been loaded by another application, OS/2 provides the 
function DosGetModHandle which returns the module handle for a dynamic link 
library that has already been loaded. This function should be issued asa test, before 
issuing DosLoadModule, in order to save on initialization time. The module 
handle is needed to get the addresses of routines within the dynamic link library 
using the function DosGetProcAddr; and for giving up access to the dynamic link 
library using the function DosFreeModule. 

OS/2 also provides two additional API functions which require the module 
handle. DosGetModName returns the fully qualified drive, path, name, and 
extension associated with a module handle. This function is used bya child process 
to learn the location ofan inherited handle. The other function, DosGetResource, 
which returns the segment selector for a resource segment, which is used like a 
shared external data segment. 


The Procedure for Run-time Dynamic Linking 


The following procedure must be followed in order to implement an applica- 
tion that uses run-time dynamic linking: 


" Dynamic Link API calls are incorporated into the application 


=" The dynamic link libraries which will be referenced by run-time linking 
calls do not have to be linked to the application during the linking process. 
However, any load-time external references will have to be resolved using 
a .lib file. 


The correct use of the run-time dynamic linking API calls are as follows: 


= The requesting process first issues the function DosGetModHandle to see 
if some other process has already loaded the dynamic link module into 
memory. In order to use this function, the process must know the full name 
(drive, path, name, extension) of the dynamic link library (.dll file) it 
wishes to access. 


* This consists of loading any segments specified as PRELOAD into memory as well as executing 
any initialization routine. 
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If DosGetModHandle returns the handle for the dynamic link module, 
then the process may go on to request the address of the routine it wishes 
to access. If DosGetModHandle returns an error, then the process must 
issue DosLoadModule so that the desired dynamic link module can be 
loaded into memory and a module handle returned to the process. 


Issuing either a successful call of DosGetModHandle or DosLoadModule 
causes an internal OS/2 counter to be incremented by one. This counter 
is used by OS/2 to keep track of how many processes are using each 
dynamic link library. 


Once the calling process has the module handle, it issues the function 
DosGetProcAddr which returns a full destination address (selector:offset) 
for the requested procedure. In order to use DosGetProcAddr, the calling 
process must know the name of the routine it is calling or its ordinal 
position within the dynamic link library. 


Once the address is known, the procedure is called using an intersegment 
CALL instruction. (See example). 


When the calling process no longer needs the dynamic link module, it 
should issue DosFreeModule. ‘This call decrements a counter kept by 
OS/2. When this counter reaches zero (1.e., when no processes are using 
the dynamic link library) it is freed from memory. 


After the calling process issues DosFreeModule, it can no longer use the 
module handle returned to it by the previous call to DosGetModHandle or 
DosLoadModule. 


Any procedure addresses returned to it by DosGetProcAddr are also 
invalid. Any attempt to invoke these locations results in a protection 
violation. The process must get anew module handle if it wishes to further 
access the dynamic link library. 


DosGetModHandle 


DosGetModHandle is used to check whether a dynamic link library has already 
been loaded by another process. A process doing run-time dynamic linking should 
issue this function before DosLoadModule, potentially saving the time it takes to 
load a dynamic link library into memory. 

DosGetModHandle returns a module handle to a previously opened dynamic 
link library. If the library is not already open the function returns error 93, “No 
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items to work on”. The function requires two arguments: a pointer to a string 
containing a fully qualified name for the requested dynamic link library and a 
pointer to a two-byte buffer where the module handle will be returned. 

A successful return of this function increments the OS/2 counter which keeps 
track of the number of processes using the dynamic link library. 


DosGetModuleHandle (ModuleName, ModuleHandle) 
char far *ModuleName; /* pointer to an ASCIIZ string containing 
the dynamic link library name */ 


unsigned far *ModuleHandle /* address in which the dynamic link 
library handle will be returned */ 





Compatability Mode Restriction 


Run-time dynamic link calls are not available in real mode. 


DosLoadModule 


DosLoadModule is used by a process to load a dynamic link library into memory. 
The function requires the name and location of the requested dynamic link library 
and returns a handle to the dynamic link library. Since this function also loads the 
library into memory, it is much slower than DosGetModHandle which merely 
returns the handle to an already loaded dynamic link library. If the dynamic link 
library specified by the function is already opened, an error #93 will be returned. 
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The function also returns the name of the object which caused its failure. If the 
call is successful it increments the internal OS/2 counter which keeps track of the 
number of processes using the dynamic link library. 


DosLoadModule (ObjNameBufAdd, ObjNameBufLen, ModuleName, ModuleHandle) 


char far *ModuleName; 


char far *ObjNameBufAdr; 


unsigned ObjNameBufLen; 
char far *ModuleName; 


unsigned far *ModuleHandle 





/* pointer to an ASCIIZ string containing 
the dynamic link library name */ 


/* pointer to a buffer containing the 
name of an object which caused the 
function to fail */ 


/* length in bytes of 
*ObjNameBufAddr* / 


/* pointer to an ASCIIZ string containing 
the dynamic link library name */ 


/* address to which the dynamic link 
library handle will be returned */ 
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Compatability Mode Restrictions 


Run-time dynamic link calls are not available in real mode. 


DosFreeModule 


Once a program is finished with a dynamic link module, it gives up access to it 
using the function DosFreeModule. This function disables all further access to the 
dynamic link library and decrements the internal OS/2 counter which keeps track 
of the number of processes using it. Ifa process needs to subsequently access the 
dynamic link library, it must issue DosGetModHandle or DosLoadModule again. 
The function DosFreeModule accepts one argument: the module handle which is 
to be freed. 


DosFreeModule (ModuleHandle) 


unsigned ModuleHandle; /* handle of dynamic link library to be 
released* / 





Compatability Mode Restrictions 


Run-time dynanic link calls are not available in real mode. 
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DosGetModName 


The function DosGetModName allows a process to determine the full qualified 
name (drive, path, name, and extension) of a dynamic library whose handle it 
already possesses. This function requires a module handle, a pointer to a buffer 
to which the string containing the name of the associated dynamic link library will 
be returned, and the length of that buffer. If the length of the buffer is less than 
the length of the string returned by OS/2, then error #382 “Supplied Buffer Too 
Small,” is generated, and the process should try the function again with a longer 
buffer length. 


DosGetModName (ModuleHandle, BufferLength, Buffer) 


unsigned ModuleHandle; /* handle of dynamic link library whose 
full name is to be returned* / 

unsigned BufferLength; /* length in bytes of Buffer*/ 

char far *Buffer; /* pointer to address of buffer to which 


the name of the dynamic link library 
will be returned* / 





Linking and Dynamic Linking 371 


Compatability Mode Restrictions 


Run-time dynamic link calls are not available in real mode. 


DosGetProcAddr 


The function DosGetProcAddr is used by a process to find out the address of a 
procedure within a dynamic link library. The process must already have two 
pieces of information in order to use this function, the module handle (inherited 
or returned by DosGetModHandle or DosLoadModule) and the name, or ordinal 
entry-point location, of the desired procedure within the dynamic link library. 
This information is found in the EXPORTS statement of the module definition file 
for the dynamic link library. The function returns a full 32-bit FAR address for the 
specified routine. This routine is accessed by the process using an assembler inter- 
segment CALL statement. 

It is possible to use run-time dynamic linking to access API functions in the 
DOSCALLS library. In this case, only the ordinal values for these routines may be 
passed to the DosGetProcAddr function (see the section on module definition 
statements). OS/2 does not support run-time dynamic link references to func- 
tions in the DOSCALLS.DLL via name strings, and any attempt to do so will result 
in an error. 


DosGetProcAddr (ModuleHandle, ProcName, ProcAddress) 


unsigned ModuleHandle; /* handle of dynamic link library which is 
being referenced*/ 


char far *ProcName /* pointer to the name string or ordinal 
of the procedure whose address is to 
be returned* / 


char far long *ProcAddress /* pointer to a double word location 
where the full procedure address will 
be returned. 
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Compatibility Mode Restrictions 


Run-time dynamic link calls are not available in real mode. 


DosGetResource 


The DosGetResource function is used by a process to get the selector associated 
with a resource segment. A resource segment is a read-only data segment which can 
be accessed dynamically at run-time. A resource segment entity allows the data for 
an application or library to be bundled into one executable file. Consequently, a 
process can use the DosGetResource call to get the selector for a resource segment 
belonging to either its executable file or a dynamic link library (whose handle was 
returned by the DosloadModule or DosGetModHandle call). 

A resource segment is identified by two 16-bit values, the resource name, and 
resource type parameters of the function DosGetResource. These two parameters 
are similar to a filename and extension, respectively. The function DosGetRe- 
source also requires, either the module handle for the dynamic link library 
containing the resource segment, or a value which indicates to OS/2 that the 
resource segment is bundled with the current executable file. The function 
returns a selector for the resource segment to a specified location. 
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DosGetResource (ModHandle, TypelD, Nameld, Selector) 


unsigned ModuleHandle; /* handle of dynamic link library which is 
being referenced*/ 


unsigned ‘T'ypeld /* type or extension identifying the 
resource segment*/ 


unsigned NameID /* name or filename identifying the 
S S 
resource segment*/ 


unsigned far *Selector /* a pointer to a memory location to 
which the selector for the resource 
segment will be returned*/ 
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Compatability Mode Restrictions 


Run-time dynamic link calls are not available in real mode. 


Example of Run-time Dynamic Linking 


MakeFile 


testdlis.ob]: teastdll3.c Compilation information 
el -@ “21 -Lp =GZe =Od testdli3.c 


testdl13.exe: testd1l13.obj ## Linking information 
link /é¢o testdll3,testd113, doscalle, lib: 


Source Code 


,* PRSTOL «3 


This program demonstrates how to make DLL calls using the run- 
time OS/2 API: 


DosLoadModule 
DosGetProcAddr. 


The previous methods for dynamic linking utililized an import 
library or specified the import functions in the DEF file. 
Using these methods commits a program to using a certain set of 
DLL functions at load-time. 


The run-time method for calling DLL functions gives a program 
the capability to choose which DLL function calls it makes 
depending on the condition of the program during run-time. This 
method is more cumbersome and should only be used only for this 
specific purpose. 
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ar 


include <doscalls.h> 


#tdefine DLL_MODULE “DLL”/* Name of the Dynamic link lib */ 
#fdefine OBJLENGTH8 0 
/* name of the DLL functions */ 
/* they should be capitalized because the 
linker only recognizes */ 
/* eapital letters */ 
ener Dll Function |2) (20) = 1° LSTRLen’,”"LeTRcPrr” | + 
unsigned (far pascal * Dl1lProcl)();/* address of the two Dll 
functions */ 
yoid (far pascal. * DllPree2){); 
main() 
{ 
unsigned ret; 


char MachineMode;/* parameters for DosGetMachineMode */ 


char ObjNameBuf [OBJLENGTH] ;/* parameters for 
DosLoad Module */ 


unsigned ModuleHandle; 


char s[80]: 
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/* determine mode of CPU */ 
if (ret = DOSGETMACHINEMODE( &MachineMode) ) 
printt(“\nDosGetMachineMode failed %d”,ret);: 


if (!MachineMode) { 


printt(*\nCannot ruh this program in DOS mede.”): 
DOSEXIT( 1,0) 


if (ret=DOSLOADMODULE((char far *)ObjNameBuf, 


OBJLENGTH, 
DLL_MODULE, 
(unsigned far *)&ModuleHandle)) { 
orintt ("Cannot find DLL file: %e.”, DLL_MODULE) : 


priate (7 \n The failed object was:%s.”,ObjNameBuf) ; 
peinti("\m  Beturn Coda: Ud, rat): 
DOSEXIT (1,0); 

} 


/* get the address of the Dll funetion 0, LSTRLEN */ 
if (ret = DOSGETPROCADDR(ModuleHandle, Dll Function[0], 


(unsigned long far *)&D11lProcl)) { 
printt(“\nCannot find procedure: %s.Return code; 


ad”, 
Dil Pumeton | 0). rer)> 
DOSEXIT (1,0) ; 
} 
/* wet the address of the Dll function 1, LSTRCPY */ 
if (ret = DOSGETPROCADDR (ModuleHandle, 
DIL Function (1). 
(unsigned long far *)&D11Proc2)) { 
printf(“\nCannot find procedure: %s. Return code: 
hd” , 


DL1l. Furmction!1), cet): 
DOSEXIT(1,0) : 
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/* we now have the entry point of the two 
functions and can call the functions*/ 


/* this call is similiar to the lstrcpy 
Call im testdill.c« */ 

(*DLlProe2 si lebar far *) a. 

tehar far *)"This if a test of DLL e@alli*>: 


/* t¢hie eall is similiar to istrilen call in teetdll.c */ 
printt ("\nstring: Se and length: %a”, 

So 5 

(*Di 1 Preel) (léehar far *)s)): 


Chapter 10 





File and Device 
[/O Functions 


S/2 file and device I/O services are based on the concept of a file handle 
QO and a data stream. To access a file or a device, it must first be opened with 

a function which returns a file handle. This file handle is used to identify 
the opened file or device when using file and device I/O functions for reading and 
writing. The data stream appears differently to application programs depending 
on whether they are accessing a file ora device. When data is being sent or received 
to or from a file, the entire data stream is available to the application. A file pointer 
is provided in order to keep track of the position within the data stream (as a byte 
displacement from the beginning of the file). (See figure 10.1) By moving the file 
pointer, an application can read from or write to any location within the file, 
making file I/O very flexible and convenient. Operating system-specific data (file 
format, block format, etc.) isn’t imbedded within the file, which makes OS/2 data 
files portable to any operating system without the need for extensive data conver- 
sion. 

Devices also treat data as a stream of bytes, but only the head or the tail of the 
byte stream is visible to the application depending on whether it is receiving or 
sending data from or to the device. Therefore a file pointer is not needed for 
device I/O. When an application writes to a device the data at the head of the data 
stream is processed by that device (i.e., itis sent over the phone line or printed out). 
The application cannot write to locations further up the data stream for fear of 
corrupting data it has already sent. When an application reads data from a device, 
the bytes arrive not in a constant stream, but in bursts. Once data is read from a 
device it is removed from the byte stream and is not available to be read again. 
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Beginnning of File 


0101010101010111 
0101010101010111 
0101010101010111 
01010101010101114 
0101010101010111 
0101010101010111 
0101010101010111 

Cs) 

8 

® 
01010101010101114 
0101010101010111 
0101010101010111 
01010101010101114 
0101010101010111 

® 





File Pointer 





End of File 





Figure 10.1 Data Stream and File Pointer. 


The file and device I/O services provided by OS/2 are very much like DOS 
function Interrrupt 21H minus the FCB’s operations. OS/2 allows an application 
to open files, read from files, write to them, and to change the location of a file 
pointer, and finally to close the file or device. It also provides file locking facilities 
for sharing data files among several applications. These file locking capabilities, 
however, are not sophisticated enough for a multiuser distributed database system 
and are just barely adequate for small multiuser file management applications. 
The file locking and data protection services necessary for the implementation of 
large distributed multiuser DBMS and the necessary database server engines, will 
probably be provided in the IBM OS/2 extended version, the Microsoft LAN 
Manager, or by Novell. 

For the C programmer, the OS/2 file I/O services are very much like those 
functions provided by the C run-time library. In fact, the syntax of most of the 
functions are exactly the same and either set of functions can be used. The 
OS/2 file I/O services are faster, but if portability to other operating systems is a 
consideration, the C library functions are recommended. 
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File and Device Naming Conventions 


File naming conventions under OS/2 are the same as those for DOS. A file 
name consists of one to eight characters followed by a period (.) and an extension 
of one to three characters. This convention, however, may be changed in future 
versions of OS/2. The starting character of the name and the extension cannot be 
a blank character (). All ASCII characters are valid except for those lower than 20H 
and the following characters: 


Crete yea FAT] 


It is possible to bypass this convention by directly modifying the sector contain- 
ing the directory entries using direct disk I/O. This kind of disk access, however, 
is not recommended. | 

Also, file names should not be the same as a device name. Device names are set 
aside for all devices supported by the operating system. OS/2 does not explicitly 
restrict a file from having a restricted device name, but whenever such a name is 
used, OS/2 looks for the the device first, before the file name. For example, if the 
user namesa file COM1, OS/2 will not return an error, but when he or she attempts 
to open the file using the function DosOpen, OS/2 will try to open communication 
port | first, before opening the file. 


Name Device Supported 

LPT1 or PRN First parallel port or parallel printer 
LPT2 Second parallel port 

LPT3 Third parallel port 


COM] - COM3 Asynchronous communication port 1 to 3. These names 
are reserved only when the asynchrounous support device 
drivers are loaded in the config.sys file. 


CON Console keyboard and screen 

KBD$ Keyboard 

SCREEN$ Screen 

NUL Dummy device (dump bucket) 
POINTER$ Pointer device (mouse screen support) 
MOUSE$ Mouse 

A: - Z: Drive names for logical drives A to Z 


Table 10.1 Reserved device names 
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File Opening Mode and File Attributes 


DosOpen opens files or devices for I/O. A file is specified by a file name, a drive, 
and directory path. A device name can only be one of the standard system devices 
listed in the previous section. DosOpen returns a file handle which is used for 
subsequent access to the file or device. DosRead and DosWrite, in conjunction 
with the file handle, read and write to the file or device. When reading or writing 
to a file, the location of the file pointer can be changed with DosChgFilePtr to 
selectively access different parts of the file. 

There are several options available to the calling program when using Dos- 
Open. If an attempt is made to open a nonexistent file, DosOpen can be set to 
either create a new file in the specified location, or to return an error. Conversely, 
ifan attempt is made to open a file that exists, DosOpen can be set to open the file, 
to open and truncate (purge) the file, or to return an error. These options allow 
the programmer some flexibility to prevent data in files from being written over, 
and to allow a program to react appropriately when it does not find an expected 
file. 

When creating a file, DosOpen requires a file attribute be specified. The 
attribute specifies whether a file is a read-only file, a system file, an archived file 
and/or a hidden file. A read-only file cannot be modified; an error is returned if 
this is attempted. A hidden file will not show up on the directory listing or any 
general search. A system file attribute specifies that a file is used by the operating 
system and should not be tampered with. An archived file is any file that has been 
modified since the last backup. The file attributes are usually identified through 
an attribute byte or a 2-byte (WORD) variable. File attributes are set using the 
parameter FileAttnbute of the function DosOpen. This parameter is a bit-mask 
value. All the possible values and meanings for the parameters’s fields are listed 
bere 
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Files can also be opened in a variety of modes which control whether they are 
to allow read and/or write access, how they are shared among several running 
applications, and whether or not they are inherited by a child process. Opening 
modes are controlled by a 2-byte (WORD) or unsigned bit mask value. The file 
opening mode or state is set using parameter OpenMode of the function DosOpen. 
The significance of each bit in this variable is as follows: 





' The volume label represents the name of the disk drive volume. It is stored as a file entry on the root directory 
that contains no data. A volume label cannot be opened. 

? A subdirectory is stored as a file entry that contains no data. It cannot be opened. 

3 Most backup systems usually turn the archive bit off after the file has been backed up. Once the file is modified, 
the archive bit is set. A backup of only modified files is then possible. 
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The access mode specified by bits 0-2 determines how the file will be accessed 
by the program that wants to open the file (i.e., whether the file will be opened for 
read or write access or for both read and write). The default access mode is read/ 
write. The possible values and meanings for these three bits are: 





Any other combinations are invalid. 


Bits 4-6 specify the file sharing mode which determines how the file is to be 
shared with other processes. The sharing mode indicates whether other programs 
can read and write on the file. The significance of the file sharing mode bits are 
as follows: 
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Any other combinations are invalid. 


The deny read/write sharing mode locks the file for exclusive use by the calling 
program. While this mode is in effect no other program can have access to the file. 
The deny read or deny write mode prohibits any subsequent attempt to open the 
file with read access or write access mode, respectively. The deny none sharing 
mode allows both read and write access to the file. Ifa file is intended to be shared 
among different programs for reading and writing, the file should be opened with 
the deny none sharing mode. 

In order for file sharing to work, all the programs involved must cooperate. The 
access mode defines how the file is to be accessed by the program that opened it, 
and the sharing mode controls the type of access other programs will have to it. 
The sharing mode specified by the first program to open a file is the most 
important factor, since it determines how a file can be accessed by subsequent 
programs. In addition, the specification of modes is cumulative. Ifa file specifies 
a certain access mode, that mode remains in effect for all subsequent access 
attempts. An access mode cannot be specified that contradicts a previous mode 
setting. To illustrate this point, we can examine a situation in which the first 
program opens a file with an access mode of read-only and a share mode of deny 
none. Another program can subsequently open the file for write access and deny 
write privileges to any programs opening the file in the future. But this program 
could not deny read, or deny read/write privileges, because the file has already 
been opened for reading by the first program. In addition, any move by the second 
program to deny write privileges will only be binding on programs that subse- 
quently open the file, not on programs that already have it open. 

In such an environment, it is generally better for each program to use the exact 
access mode it requires, instead of using the default of read/write. Ifa program 
only needs to read a file, it should specify read-only access mode. If the file has 
already been opened by another program with any sharing mode other than deny 
none, a file open request with read/write access mode will fail. In the compatibility 
box, the access mode and sharing mode are only valid if the Share command is 
loaded. 
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The DASD (direct access system device) option bit specifies whether direct access 
to the device is possible. For file I/O or device I/O, the DASD option should be 
set to zero, or disabled. When a logical disk drive is opened with the DASD option 
bit set to one, the whole drive is treated as a single file and the returned file handle 
can only be used for direct drive access using IOCTL category 8 function calls via 
function DosDevIOCTL. Generic IOCTL calls are discussed in Chapter 8. This 
option of drive opening should be used for system programs and not by applica- 
tions. 


DosOpen and DosClose 


As mentioned earlier, DosOpen opens a file or device for input and output 
purposes. The file or device is specified with either a file name or a device name. 
When the program no longer needs the file or device, it should close the file using 
DosClose. When the file is closed, any access restrictions placed on it through the 
sharing modes no longer hold. If the file has been bufferred, the buffer contents 
are written to the disk drive. Also, any changes in the file’s attributes or size are 
updated on the drive directory. 

A file name can include the drive and/or the directory path where the file is 
located. A hidden file or a system file can also be opened. Only subdirectory or 
volume entries cannot be opened. A device name must be one the standard devices 
recognized by the system. A system which is based on the PC family can recognize 
only three parallel ports (LPT1:, LPT2:, LPT3:) and two communication ports 
(COM1:, COM2:). A PS/2-based system can recognize three asynchronous com- 
muication ports, COM1: through COM3:, and 4 parallel ports from LPT1: to 
LPT4:. If the device is the disk drive, the drive letter must be specified. In order 
to open a drive for IOCTL access the DASD option bit should be set (see the 
discussion in the previous section), otherwise it should be off. The system also 
recognizes device names such as STDIN, STDOUT, STDERR. 

DosOpen returns a file handle which identifies the file or device for subsequent 
I/O operations with DosRead and DosWrite. When a device is opened it is treated 
as a single file. DosRead and DosWrite can be used to send output or accept input 
from the device. No file pointers, however, are maintained for physical devices. 
Therefore, functions such as DosChgFilePtr are not valid for use with a device 
handle. PC compatible computers cannot accept input from parallel ports, but 
PS/2 computers can. In order to perform I/O on an asynchronous port, the 
communication port must be initialized with the baud rate, parity, stop bits, xon/ 
xoff status, etc. The communication port or the parallel port is initialized using the 
OS/2 Mode command, or with generic IOCTL functions using DosDevIOCTL. 


File and Device |/0O Functions 387 


DosRead and DosWrite cannot be used for I/O on physical disk drives, these 
require IOCTL functions. Chapter 17 discusses how to use IOCTL functions to 
manipulate the asynchronous port, printer port, video screen, keyboard, mouse, 
and disk drives. 

DosOpen can be used to create a new file. The file size in number of bytes and 
its attributes must also be specified. The parameter OpenFlag, an unsigned or 2-byte 
(WORD) variable, specifies the options that DosOpen uses to determine whether 
to create a file or not. 

A 2-byte or unsigned value is returned to the variable A ctionTaken informing the 
calling program of the action taken by the function. 


DosOpen (FileName, Handle, ActionTaken, Size, FileAttribute, OpenFlag, OpenMode, 
Reserved) 


char far *FileName; /* pointer to the file name string */ 

unsigned far *Handle; /* pointer to the returned file handle */ 

unsigned far *ActionTaken; /* action taken by the function */ 

long unsigned Size; /* new file size, used for the create 
option */ 

unsigned FileAttribute; /* new file attribute */ 

unsigned OpenFlag; /* open or create option */ 

unsigned OpenMode; /* file opening mode, bit mask value */ 


long Reserved; /* must be zero */ 
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DosClose (FileHandle) 


unsigned FileHandle; /* file handle of the file or device to be 
closed */ 
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Compatibility Mode Restrictions 


The compatibility mode includes several features which are not supported by 
DosOpen. They are: 


" File sharing features, such as the share mode, and the access mode, are only 
applicable if the Share program is loaded. This is only necessary when a 
DOS application and a protected-mode application use the same file. Ifthe 
program Share is not loaded, these modes are ignored. The default 
sharing mode is deny none. Even when a file is opened in read-only access 
mode, it will have the deny none mode allowing read/write access to other 
programs. 


=" The file buffering option bit must be set to zero or off. 


# The error handling option bit must also be off or zero. 


DosSetMaxFH 


This function allows a process to override the default limits on opened file 
handles specified in the “config.sys” file. This function allows file I/O intensive 
programs to receive the services they require. Remember the limit on the total 
number of handles opened across the entire system (file, device, and pipe) is 255. 


DosSetMaxFH (NumberHandles) 


unsigned NumberHandles; /* number of file handles */ 
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File 1/0, File Pointer, and File Protection 


As mentioned earlier, a file is considered to be a byte stream. The beginning 
of file (BOF) is the beginning of the stream, and the end of file (EOF) is the end 
of the stream. A file pointer points to the location where file access begins. 

When the file is opened, the file pointer is automatically at the BOF or at 
location zero. If the program reads or writes 20 bytes, the file pointer is moved to 
location 20 or to the location after the last byte that has been read or written. The 
next read or write starts from that location unless the program moves the file 
pointer. The EOF will have a location number equal to the size of the file. Suppose 
a file is 328 bytes long. The EOF will be at location 328 with the BOF at location 
Zero. 

In a multitasking environment several programs will often have access to the 
same file. Data can be accidentally overwritten without some form of file 
protection. OS/2 offers a rather simple file protection scheme which restricts file 
access using the access mode and sharing mode specified when the file is opened. 
A file can be shared among different programs by specifying read/write access 
mode and deny none sharing mode. Each program with the file opened in these 
modes can read from or write to the file at any location. 

This scheme of file sharing works fine as long as each program restricts its 
activity to modifying a separate section of the file. But if several programs modify 
the same section of the file, data can be easily overwritten. For example, if several 
programs can modify a record in a file which maintains a total amount, in order 
to change this amount, a program needs to read the original amount from the file, 
either add to or subtract from it, then write the new value to the file in the same 
location. Suppose programs A and B both read this total amount at the same time. 
Program A adds to the total and writes the new total to the file. Immediately after, 
program B writes a different total to the same location. The value currently stored 
in the file is no longer valid. It only reflects the changes to the original made by 
program B and not by program A. 

In order to solve this problem, OS/2 allows a program to protect a certain 
section ofa file from being changed by another program. This is called file locking. 
It is not a fool-proof file protection mechanism. It assumes that the two programs 
sharing the same file will cooperate with each other. Let's look at our previous 
example again. Program A first reads the total amount and then locks the file 
section containing the record from any type of access by any program. Both 
reading and writing access are prohibited once the section is locked. When 
program B requests to lock the record, it will be notified that the section is already 
locked. Program B must wait until the file section is unlocked by program A before 
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it can read the record. Once program A has changed the value of the amount, it 
should release the file lock. This means that program B will read in the correct 
value of the total amount. 

Let’s summarize the types of file protection. First, we can specify a file with a 
read-only attribute which protects it from being modified by any program. When 
a file is opened, a sharing mode for the file can be specified which restricts the types 
of access granted other programs. Finally, certain sections of the file can be 
selectively locked to insure that they will not be overwritten by another program 
(while other sections of the file continue to be modified). However, this file 
protection scheme is not complex enough for multiuser database operations, 
where several users can have access to the same file and totally inadequate for a 
distributed multiuser database system. The facilities required for a distributed 
multiuser DBMS will probably be provided by the Microsoft LAN Manager or the 
IBM OS/2 Extended Edition Lan Server. 


DosRead 


DosRead reads a specified number of bytes from a file. The file is specified with 
the file handle returned when the file was opened via DosOpen. The number of 
bytes to be read is specified by the variable BufferLength. A pointer to the buffer 
where the read data is placed is indicated with the variable BufferArea. The buffer 
should be large enough to contain the number of bytes requested. DosRead 
returns the number of bytes that have actually been read from the file. If this is zero 
or less than the requested length, and no error code is returned, the end of the file 
has been reached. This is the only way for a program to determine the end of file 
condition. The programmer should recognize and deal appropriately with this 
condition. 


DosRead (FileHandle, BufferArea, BufferLength, BytesRead) 


unsigned FileHandle; /* file handle */ 

char far *BufferArea; /* pointer to the buffer which will 
contain the data */ 

unsigned BufferLength; /* number of bytes to be read from the 
file */ 

unsigned far *BytesRead; /* pointer where the value of the number 


of bytes actually read will be returned*/ 
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DosWrite 


DosWrite writes a specified number of bytes to a file or a device. The file or 
device is specified with the file handle that was returned by DosOpen. The number 
of bytes to be written is specified with the variable BufferLength. A pointer to the 
buffer which contains the data to be written to the file or device must also be 
specified. DosWrite returns the number of bytes that were actually written to the 
file or the device. If DosWrite reports that less bytes than were requested, or no 
bytes atall, were actually written to the file, and if no error code was returned, then 
there isno more disk space available. The program should recognize this error and 
notify the user immediately. If the program creates temporary files, it should try 
to erase these files in order to avoid such a situation. If this problem arises when 
writing to a device, then the device may have trouble dealing with large amounts 
of data. 

Because it involves the manipulation of mechanical devices, writing data to a 
disk is one of the slowest operation in acomputer system. Therefore, reducing the 
number of times the operating system actually outputs data to a disk, increases the 
performance of the entire system. Physical storage devices are divided into sectors 
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(hard drives) or tracks (diskette). Each sector or track stores n number of bytes. 
The number of bytes per sector or track represents the size of the basic physical unit 
which makes up the device. The number of bytes per sector is 1K and per track is 
512 bytes. DosQFSInfo (see Chapter 11) returns the number of bytes per sector 
and other parameters, for your disk. The most efficient way to write to a storage 
device is to write one sector or one track at a time, or n bytes ata time. Writing to 
a disk in multiples of the size of the basic physical unit ensures the best possible 
system performance. 

OS/2 writes data to the disk in multiples of the basic physical unit (1K or 512 
bytes ata time). When writing a number of bytes that is not a multiple of the basic 
physical unit, the operating system stores any excess data in an internal buffer. This 
excess data is written to the disk when enough data has accumulated to write a full 
basic physical unit, or when the file is closed. This procedure is called file I/O 
bufferng. A program can disable file I/O buffering by setting bit 14 of the OpenMode 
parameter when it opens the file using DosOpen (see page 5). When file buffering 
is disabled, data is written to the disk at once. No buffer is maintained for the file. 
This insures that no data is lost during a system or power failure. If a program 
wishes to take advantage of file buffering, but wishes to ensure the contents of a 
buffer are written to the disk, it can use DosBufReset, which clears the contents of 
a buffer by writing it to the disk. 


DosWrite (FileHandle, BufferArea, BufferLength, BytesRead) 


unsigned FileHandle; /* file handle */ 

char far *BufferArea; /* pointer to the buffer area containing 
the data */ 

unsigned BufferLength; /* number of bytes to be written to the 
file */ 

unsigned far *BytesRead; /* pointer to the memory location where 


the value of the number of bytes 
actually written will be stored*/ 
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DosChgFilePtr 


DosChgFilePtr moves the file I/O pointer to a specified location on the data 
stream. You specify which file with the file handle returned by DosOpen. 

DosChgFilePtr supports three methods of moving the file pointer: move to a 
location a number of bytes from the beginning of the file, move to a location a 
number of bytes relative to the current location, or move a number of bytes from 
the end of the file. The type of move is specified by the variable MoveType and the 
number of bytes to move is specified by the variable Distance. 

To start from the end of the file and move the file pointer backward to a valid 
location on the data stream, the value of Distance must be negative number. 
Moving beyond the end of the file or the beginning of the file is not possible. When 
the Distance value places the file pointer beyond these points, the file pointer is 
placed at the BOF or the EOF point instead. 

DosChgFilePtr returns a 4byte or long value indicating the new file pointer 
position, NewPointer. NewPointer represents the file pointer position as a number 
of bytes from the beginning of the file. A program can determine the current file 
size by setting MoveType to 2 and Distance to zero, indicating that it wishes to place 
the pointer at the end of file (zero bytes from EOF). The value returned by 
DosChgFilePtr indicates the current size of the file. 


DosChgFilePtr (FileHandle, Distance, MoveType, NewPointer) 


unsigned FileHandle; /* file handle */ 
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long Distance; /* number of bytes to move. This value 
can be negative indicating moving 
backward */ 


unsigned MoveType; /* moving method */ 


long far *NewPtr; /* pointer to the value of the new pointer 
location */ 
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Example 1 - LIST 


/* LIST.C 


This program demonstrate how to use disk I/O. It will not take 
advantage of OS/2 multi-tasking capabilities. 


This program will simply display an ASCII text file on the 
screen, It will use several VIO API functions which we have not 
discussed yet. These functions, however, are very simple. 


af 


finclude “stdio.h* 
#include “doscalls.h” 
#include “subcalls.h” 
#include “dos.h” 


##tdefine O_FAIL 0x0000 /* constant for DosOpen */ 
4tdefine O_OPEN 0x0001 

tt}define O_REPLACE 0x0002 

+#define O CREAT 0x0010 /* ereat if file not existe */ 
ffdefine DENY_READ 0x0010 /* sharing mode */ 

4#tKdefine DENY WRITE 0x0020 

}t}define DENY_NONE 0x0040 

+#define READ ONLY 0x0000 /* Access mode */ 


ttdefine WRITE ONLY 0x0001 
4tdefine READ WRITE 0x0002 


4¢edefine CR OxOD 
+#define LF OxOA 
4edefine TAB 0x09 
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4tdefine BUFLEN 512 
tt}define STACKSIZE 4000 


wold display () ; 
void outdisp(); 
void cleat): 


/* global variable */ 


main (argc,argv) 
LiG eras 


{ 


char far 
enar far 


unsigned 


unsigned 
unsigned 


long fsizel, 


long 1; 


char *argvl]; 


*rair t's 
* Dit 2 s 
Selecterl, Selector2: 


/* parameters for DosOpen */ 


fol, rd2% /* Tile deseripter land 2 */ 
ActionTaken; 
£SiZe?2: y* ile sige */ 
/* temporary war */ 


long bytesreadl, bytesread2; 


unsigned 
unsigned 


cher far 
char far 
unsigned 


unsigned 


unsigned 


it (ares 


butler : 
Dur len? : 
oe 
*Stack: 
ret,i; 


/* far pointer to thréeed stack (word) */ 


thread id: /* param for DosGreateThread */ 


/* flags to determine when to stop 
reading 


stopl, stop2: 


af 


< 2) | 
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printf(“\nCommand Format: LIST <file_name>”) ; 
prince’ ("va eg.: LIST autoexec.bat”) ; 


DOSEXIT(1,0); 


/* epen File */ 
ret = DOSOPEN( (char far *)argv([il, 
(unsigned far *)&fdl, 
(unsigned far *)&ActionTaken, 


ee /* N/A WHEN OPEN AN EXISTING FILE */ 
0, ys same as above */ 

O_OPEN, 

DENY_NONE | READ_ONLY, /* open mode */ 

OL) ; 


if (ret) { 
printf(“\nDosOpen failed: %s %d”,argvl1l],ret); 


DOSEXIT (1,0); 


/* using DosChgFilePtr to get file size */ 
/* by moving the File ptr to eof */ 
DOSCHGFILEPTR (fd1l, OL, 2, (long far *)&fsizel); 


rec 


ret = DOSCHGFILEPTR (fd1, OL, 0, (long far *)&1): 


buflenl = (int)fsizel; 
/* alloc the memory buffer for the file */ 


/* tivis will mske it impoeeible for */ 

/* the program to list files larger */ 

/* than 64K. This simplifies the complexity */ 
/* of the prosram. *7 


ret = DOSALLOCSEG (buflenlitl, 
(unsigned far *)&Selectorl, 


it 


te (fen) 4 
printf(“\nDosAllocSeg failed %d”,ret); 


DOSEXIT (1,0) 3 


FP SEG(bufl) = Selectorl1; 
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FR OFF (purl) = 8; 


/* ~ead the contents of thea Files */ 
Stet 4 


ret = DOSREAD(fdl, /* read from file */ 
(ener far *) burl, 
buflenl, 
(unsigned far *)&i); 


*(putltbutlenis ="0?. 


if (ret) { 
printft(“\nError reading %s error: %“d*,arev[i], ret); 
DOSEA ITY LO) ; 


/* agsieoned arsument to the thread stack */ 
display (bufl) ; 


DOSCLOSE Cid): 
DOSFREESEG(Selectorl); 


void display (buf1) 
ener tar “paris 
{ 
char far "“startl: 
share fae “gl 
static int count=0; %/* line esunt */ 
unsigned diff; 


etartl = €) = burl; 


Lit. = 
while (1) { 
i* deteruine the etart of line */ 
if (*s1 == (char) LF ) { 
tei o's g* 22 start of line */ 


eountt+:; /* then digplay previous line */ 
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outdisp(startl); 

start] = +tale /* point te The méxt. lane */ 
} 
a2 [Pela SSA 

break; 


void cle) 


{ 


char c[2]: 
e(O} = * *; #* eell te replicate is a blank */ 
efi) = 7: /* with normal attributes */ 


/* @¢lear sereen by calling VIOSGROLLUP */ 
VIOSCROLIUP(O, GO, =—ly -ly -l, (ebar tar “ie, Gy; 


unsigned lstrlen(s) " 
cher far “es: 
{ 

Int 3 

ener tar *t: 


t= <¢ 

poe o- 

while (*et+ 1="\@") 
a es 


return (4) : 


void outdisp(sl) 
char far *213 
{ 
ie. a" 
char temp[40], c: 
static int row=0: 


/* API funetion to display an ASCII string to the screen */ 
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VIOSETCURPOS (rowt+, /* get cursor postion to row &*/ 
Oy f* eo lame > / 
see j* wie hendla *7 


VIDOWRITTY ((char far *)sl, /* write string to screan */ 
istrien(¢sl1)., 
as 
if (row 2 23) { 
strepy(temp,”Press any key to continue”); 
VIOWRTCHARSTR( (char far *)temp, 
strlen (temp) . 


row, 
O, O14 
a= 10": 
while (c == ‘\0’) 
¢ = getch(): 
roy = De 


elest): 


Example 2 — DIFF 


/* DIFF .C 


This program demonstrate how to use disk.I/O0. It will not take 
advantages of 05/2 multi~taskines capabilities. 


This program compares two ASCII files and displays the 
difference on a line-by-line basis. The program is merely a 
demonstration tool and not a commercial program. Therefore, 
help features are not included. 


The program also use several VIO API functions to display data 
on the screen. These functions, however, are simple and self- 
explainatory. 


ae 


#Hinclude 
4#tinclude 
#Finclude 
fFinclude 


+#define 
define 
+#define 
+#define 


+#define 
+#define 
+#define 


+#define 
+#define 
+#define 


+#define 


+#define 
+#define 


+#define 
+#define 


vyoLd die 


"“estaio.h” 
“doscalise.h” 
“supealile, h” 
“dos. i” 
QO FAIL Ox0000 
QO OPEN Ox0001 
O REPLACE Ox0002 
O CREAT Ox0010 
DENY READ Ox0010 
DENY WRITE Ox0020 
DENY NONE Ox0040 
READ ONLY Ox0000 
WRITE ONLY Ox0001 
READ WRITE Ox0002 
ean OxOD 
LE OxO0A 
TAB Ox09 
BUFLEN 512 
STACKSIZE 4000 


play(); 


void compare(); 


void cls 


/* global variable */ 


main (ar 
If arpe 
char *ar 
{ 
char 
char 


unsigned Selectorl, 


(2% 


gc, ,arav) 


evil: 


tar *putl: 
tar “put Z: 


Selector? : 


/* 
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constant for DosOpen */ 


ereat if file not exists */ 


sharing mode */ 


Access mode */ 
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/* parameters for DosOpen */ 
unsigned fdl, £d2; (* file déserfipter 1 and 2 */ 
unsigned ActionTaken; 


long fsizel, fsize2; /* Pile gizge */ 
long 1; /* temporary var */ 


long bytesreadl, bytesread2; 


unsigned buflenl1; 
unsigned buflen2; 


char tar *e: 
char far *Stack; /* far pointer to thread stack (word) */ 


unsigned ret,i; 


unsigned thread_id; /* param for DosCreateThread */ 
unsigned stopl, stop2; /* flags to determine when to stop 
reading */ 


if taree < 3) 4 
printf (*\nCommand Format: DIFF <filel> <file2>"): 
printt(“\o eg : DIFF autoexec.bat autoexec.os2”); 
peantt tn will display the differences 
between the two files”); 


DOSEXIT (1,0) 3 


/* open firet file */ 
ret = DOSOPEN( (char far *)argevi1i, 
(unsigned far *)&fdl, 
(unsigned far *)&ActionTaken, 


OL, /* N/A WHEN OPEN AN EXISTING FILE */ 
ar ie same as above */ 

O_OPEN, 

DENY_NONE | READ_ONLY, /* open mode */ 
OL); 


if (ret) 4 
printf(“\nDosOpen failed: %s %d”,argv[1],ret) ; 
DOSEXIT(1,0); 
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ret = DOSGPEN( (cher far *)arey|2]., 
(unsigned far *)&fd2, 
(unsigned far *)&ActionTaken, 


On. /* N/A WHEN OPEN AN EXISTING FILE */ 
0, i. same as above */ 

O_OPEN, 

DENY_NONE | READ_ONLY, /* open mode */ 
OL); 


if (ret) { 
printf(“\nDosOpen failed: %s %d”,argv[2],ret); 


DOSEXIT(1,0): 


/* using DosChgFilePtr to get file size */ 
ret = DOSCHGFILEPTR (fdl, OL, 2, (lone far *) &fsigel }: 
ret = DOSCHGFILEPTR (fd2, OL, 2, (leng far *)&teize2Z); 


/* move the pointer back to the BOF */ 
ret = DOSCHGPILEPTR (fdl, OL, 0, (lone tar *) G1): 
ret = DOSCHGFILEPTR (fd2, UL, 0, (lens far *)/a1)2 


buflenl = (int) fseizel: 


buftlen2 = (int)feize2; 
/* allocate memory for butter 1 and botfer 2*/ 


i* this will make at impossible for */ 

/* the program to procese files larger */ 
/* than 648. This 26 néeessary to make */ 
/* the program simpler. */ 


ret = DOSALLOGSEG (buflenitl, 
(unsigned far *)&Selectorl, 
O)3 
if (ret) { 
printt(*\nDosAllocSesa Failed “d”,ret) ; 
DOSEXIT(1,0); 


FP SEG(buf1) = Selectorl: 
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EP OFP (burl) = 0: 


ret = DOSALLOCSEG (buflen2+2, 
(unsigned far *)&Selector2, 
ai 
if (ret) { 
printf ("*\nDosAllocSes (2) failed %d",ret): 
POSEXIT (1,0) 3 


FP SECG(but2Z2) = Selector2: 
FP OFF(buf2) = 0; 


/* so far we have two files opened and two memory buffer */ 
/* we will read the contents of the files and compare them */ 


bytesreadl = OL; 
bytesread2 = OL; 


Sropl = stop2 — U2 
elet}s 


ret = DOSREAD(fdl, /* vead from file 1 */ 
(ehar far *) burl, 
buflenl, 
(unsigned far *)&i); 


*{puritbuFleant) =*\0); 
if (ret) { 
printt(“\nError reading %s error: %d 
argv[l], ret); 
DOSEXIT(1,0); 


99 


/* read inte buffer 2 */ 


ret = DOSREAD(fd2, /* ead from file 2 */ 
(char fac *) but2; 
buflen2, 
(unsigned far *)&i); 


* (buf2+buflen2)= ‘\0’: /* make the last char null */ 


} 


/* 
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if (ret) | 
printf(“\nError reading %s error: %d 
argv[2], ret); 
DOSEXIT (1,0); 


99 


/* assigned argument to the thread stack */ 
compare (bufl,buf2) ; 
DOSCLOSE (dl) 3 
DOBCLOSE(fd2)'s 


DOSFREESEG(Selectorl); 
DOSFREESEG(Selector2); 


separate thread */ 


void compare (bufl,buf2) 
char far *putl: 
char tar *purt2Z: 


char far *stertl: 

char far *startz: 

char far *s1: 

char far *s2; 

static int count=0: /* line count */ 
unsigned diff; 


getartl = sl — burl: 


etartz2 = 62 = bur2: 
aiff = 0: 
while (1) { 

/* determine the start of line */ 

if {*6il == (char) LF) { 
CounttT ; 
ae (etree 4 /* 4f previous line was */ 
display lstarti . /* different, display */ 


atertr?,. /* both lines */ 


407 
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ula 


eount ) : 


} 
starcl — +tele /* point te the text line */ 
dar Ss 


/* moves to the next line of the other buffer also */ 


woile ("62 T= 'yord- { 
if (*g2 == (char) GR) /* null ottt CRLF */ 
*s2 = *\0" s 
if (*62 == ([enar) LF) { 
teat = PVs 
break; 
eZtr: 
af (*#g2? t= *.0") 4 
SLari2 = rez: 
} else 
featarts = “4.073 
(*s2 == (char) LF) { 
counttr: 
it Leer) 


digeplay(atartl,gtart?,ceunt); 


} 
Starts. = rre2: 


Ctr = i) 3 
while (€*sl. t= *\0") 4 
if (*61 =—— Uchar) CR) /* tull out CRLEY */ 
*s1 = *\o’: 
if (*61 — lehar) LF) | 
tale = 80" 
break; 
} 
aera 
} 
if’ ("el t= *10*) 4 


efertl = rel: 


{ 


} else 
PSeLart | 
} 
17 {*% 6) }= *e7) 
ar SS 1S 
if (*el =—— FLO’ 
break; 
sf {*ei1 != *\0’ 
arr: 
4£ (*82 1=] *\6? 
Sarr 
} 
void cls() 
char c[2]: 
c[O] = 
c{l] = 7; 


erstrepy (tarset, source) 
char far 
char far 


{ 


¥VIOSCROLLUP(O, 


enar far *t: 
Char far *e: 
ink 13 


a. = gource: 
t = tareet: 
= Je 


while (*¢ != 


*target; 
*source; 


oF 


eG 8 he 
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*s2 == ‘\0") 


/* eell ta réeplieate is 4 blank */ 
/* with normal attributes */ 


-], -l, tehar far *)e, 0): 


/* gtrepy but only up to CR or LE */ 


*c I= (char) CR) { 
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ars 

*ttt = *gt+: 

47 (a 2 25) /* only display 25 characters of line */ 
break; 


void display(el1.,62,count) 
cher tar “el: 

ener far “ez: 

int count; 

{ 


Static ant fow = 0: 


char temp[40]:; 
char c; 


LIE 3 


sprinti (cemp, "Line: %d\0", count): 
VIOWRTCHARSTR(temp, 
strien(temp)., 
row, 
0, 
OS 


eretrepy( (char far *)téemp.e1): 
VIOWRTCHARSTR ((char far *)temp, 
strlen (temp) 
row, 
Les 
Os 


eretrepy( (char far *} temp, 62): 
VIOWRTCHARSTR ((char far *)temp, 
etrlen(temp) , 
rowrt, 

40, 
0); 
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strcepy(temp,”Press any key to continue”) ; 
if {row > 23) { 
VIOWRTCHARSTR( (char far *)temp, 
strlen(temp), 


row, 
OG; O)% 
c=} "\0': 
while (c == ‘\0’) 
c = getch{): 
row = 0; 
elel): 


File locking and DosFileLock 


DosFileLock locks or unlocks a specified region of a file. The file is specified 
by the file handle. The file region to be locked or unlocked is delimited by a file 
pointer position (file offset) and the length of the region in bytes. For example, 
to lock the region from byte number 5 to byte number 200, the starting offset would 
be 5 and the length would be 195. 

As explained on page 12, locking a region of a file prevents any attempt to read 
from or write to the region. If a program wishes to protect a section of a file, it 
should be locked before it is accessed. Ifan error code is returned, then the region 
has already been locked by another program. The program must then wait until 
the region is lockable again. Any attempt to unlocka region thatis currently locked 
by another program is ignored. 

DosFileLock expects three parameters: the file handle, the file range to be ~ 
locked, and the file range to be unlocked. The file handle is specified by the 
variable FzleHandle. The file range to be locked is indicated by a pointer LockRange 
which points to an 8-byte memory block containing the offset and the length of the 
region. Similiarly, the file range to be unlocked is indicated by the pointer 
UnlockRange, which also points to an 8-byte data structure. 

If either UnlockRange or LockRange is a null pointer, this indicates that either 
unlocking or locking, respectively, is not specified for that call. Because of the 
structure of the function a program can unlock a region of a file and lock another 
region with the same call. If the RangeLength argument specifies a region beyond 
the EOF, no error is returned. The function will lock or unlock from the starting 
offset to the EOF instead. Ifa region of a file is to be locked by a program, then 
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no part of that region, no matter how small, may have previously been locked by 
another program. | 

The locking or unlocking ofa file region is done on the basis of files and not file 
handles. This means that if the program has several handles, all of which specify 
the same file*, and a region of that file has been locked using one of the handles 
related to that file, the region can be unlocked using any of the other file handles. 


DosFileLock (FileHandle, UnlockRange, LockRange) 


unsigned FileHandle; /* file handle of file region to be locked/ 
unlocked */ 


struct LockRange far *UnlockRange; /* pointer to the unlocked range info */ 


struct LockRange far *LockRange; /* pointer to the locked range info */ 





*DosDupHandle can be used to create several file handles which refer to the same file. 
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DosBufReset 


DosBufReset instructs OS/2 to write the current file I/O buffer immediately to 
the disk drive. The function causes OS/2 to update the directory information 
relating to the file (1.e., new file size, new last access date etc.) A file handle 
specifying the file to be updated is required. If the program uses a file handle value 
of -] or FFFFH, all file [/O buffers currently opened by the program are written to 
the disk and the directory information for all these files is updated. 

This function is used by the program to insure that any valuable changes made 
to a file will be actually written to the disk. This prevents data loss in the file buffers 
due to a system or power failure. DosClose also writes the contents of a specified 
buffer to the disk, but DosBufReset keeps the file open for further I/O. 


DosBufReset (FileHandle) 


unsigned FileHandle; /* file handle of the file to be updated */ 
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Standard 1/0: STDIN, STDOUT, and STDERR 


In addition to devices that may be explicitly opened by a process, all OS/2 
processes automatically have access to the following standard I/O devices: STDIN, 
STDOUT, and STDERR. These devices are accessed by file handles, 0, 1, and 2, 
respectively. There is no need to call DosOpen before manipulating these devices 
as they are placed at the disposal of a process at start-up time. 


# STDIN, or Standard Input, can be used as the standard input character 
stream for a process. It is typically set to the console (CON) device handle, 
which allows a process to receive data from the keyboard with DosRead. 


#® STDOUT, or Standard Output, can be used by a process to output character 
data to the video screen, using DosWrite. In order to do this, itis associated 
with the console (CON) device handle. 


#® STDERR, or Standard Error, instructs OS/2 where to send Error informa- 
tion. If error messages should be sent to the screen, STDERR should also 
be set to the console device handle (CON). 


Using the standard I/O handles allows a process to communicate with the user 
(accept keyboard input and send output to the screen) in the same way that a 
process communicates with any other character stream device. This means that a 
process using standard I/O can only write to the rear of the data stream being sent 
to the video screen, or read from the head of the data stream being sent to it from 
the keyboard. This provides a process with an I/O interface about as sophisticated 
as that of an old-fashioned TTY device. In fact when a process uses DosWrite and 
STDOUT to write to the video screen, the video subsystem function VioWrtTTY is 
invoked. The function provided by standard I/O will be sufficient for certain 
applications and utilities. Using standard I/O such programs can avoid using the 
API supplied by the keyboard and video subsystems. 

We said that the STDIN, STDOUT, and STDERR are automatically available for 
use by a process at start-up time. However, these devices must have previously been 
associated with the device handle of of a valid OS/2 device. Processes inherit 
STDIN, STDOUT, and STDERR from their parent process. The first process 
within a session inherits the handles from the command processor. Because the 
I/O model for the standard I/O model is so simple, it can be associated with a 
number of different devices. 

Because an OS/2 process inherits STDIN, STDOUT, and STDERR from its 
parent, a parent process can control the standard I/O environment for any of its 
children. For example, the main process in an application can choose to provide 
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input to a child process through a pipe or a file, instead of allowing it to directly 
access the keyboard, by associating STDIN with a pipe or a file handle, instead of 
the console (CON). In the same way STDOUT for a child process can be set toa 
file handle instead of the console video screen*. Using DosDupHandle, the stan- 
dard input or output for a process can be routed to almost any file handles - 
belonging to either a file, a device or a pipe. 


DosDupHandle 


DosDupHandle allows a process to associate a new file handle with the file, 
device, or pipe, represented by any valid opened file handle. The function can be 
used in two ways. The first simply creates a new file handle which is a duplicate of 
the original. The second associates an already existing file handle with the file, 
device, or pipe represented by another valid file handle. This latter option is used 
to re-direct I/O for processes and threads. 

The function expects two parameters. The first, OldftleHandle, is any currently 
opened file handle. The second, NewfileHandle, is either a currently opened file 
handle in which case the new file handle replaced the old one, or the value 
“FFFFH” which makes a duplicate file handle. If the latter option is chosen, the 
new file handle is returned in the parameter NewFileHandle. After the function 
is called, any I/O operations involving NewFiledandle will affect the file, device, or 
pipe represented by OldFileHandle. 


DosDupHandle (OldFileHandle, NewFileHandle) 


unsigned OldFileHandle; /* handle of a currently opened file */ 


unsigned far *NewFileHandle; /* pointer to the new file handle */ 





°As you learn later on, in Chapter 12, the redirection of standard I/O is one method by which a background 
process can (indirectly) receive input from the user and (indirectly) send output to the video screen. 
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Example 


/* this example demonstrates how to redirect the STDIN to 
gnéther rile */ 

unsigned NewFileHandle; 

unsigned OldFileHandle; 


/* assumed that OldFileHandle is the handle of an opened file 
via DosOpen */ 


NewFileHandle = 1; j/* value for STDIN */ 


DOSDUPHANDLE (OldFileHandle, (unsigned far *) &NewFileHandle) ; 


Chapter 11 


Disk, Directory, and 
File Management 





management. [his chapter will hold no surprises for experienced DOS users, 

since OS/2 uses the same logical disk organization as DOS. Information on a 
disk is stored in files which are organized into subdirectories. Information on each 
file is stored in three separate areas: the FAT (File Allocation Table) area, file 
organization information, and the actual data contained within the file. 

The currentversion of OS/2 retains the DOS disk format to ease migrating DOS 
data to the new environment. This, however, has two drawbacks. First, OS/2 
cannot recognize a logical drive larger than 32MB. Second, and of more serious 
consequence, is the fact that DOS places information on each file in three separate 
locations. This means that every time a file is read, all three disk areas must be 
accessed. In a multitasking environment where several files are opened simulta- 
neously, this results in a lot of disk head movement. All this movement of 
mechanical devices adversely affects the performance of the system. 

Future versions of OS/2 will probably allow for an alternate disk logical 
format—one tailored to the requirements of a multitasking environment. For 
example the UNIX disk logical format stores all information needed to access a file 
in a single location. Thus movement of the disk heads is minimized. 

There are very few new functions for OS/2. Most are very similar to those 
provided by Int 21H under DOS 3.3. The following is a synopsis of the disk, 
directory, and file management function. 


| n this chapter we discuss the API functions used for disk, directory, and file 


Disk Functions 


DosQCurDisk Returns the current default disk drive for a program. 
DosSelectDisk Chooses a new default disk drive for a program. 
DosQFSInfo Returns information on a disk or volume label 


information. 
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DosSetfSInfo 
DosPhysicalDisk 


Sets the volume label for a disk. 


Returns the number of partitions on a hard drive or 
returns a file handle for use with direct disk I/O IOCTL 
functions. Low level disk functions are covered in 
Chapter 18. 


Directory Management Functions 


DosQCurDir 
DosChDir 
DosMkDir | 
DosRmDir 


Returns the current default directory for a program. 
Changes the current default directory for a program. 
Creates a subdirectory. 


Removes a subdirectory. 


File Management Functions 


DosQFHandsState 
and 
DosSetFhHandState 


DosQHandT ype 


DosQFilelnfo and 
DosSetfilelnfo 


DosQFileMode and 
DosSetFileMode 


DosNewSize 


DosQVenfy and 
DosSet Verify 


DosSearchPath 


Doskindfirst, 
DoskindNext and 
DoskindClose 


DosMove 
DosDelete 


Return and set the value of the OpenMode parameter 
used with the function DosOpen. This parameter 
controls the file opening mode. 


Determines whether a file handle is associated with a file, 
a device, or a pipe. 


Determine and set the attributes for a file. 
Determine and set file attributes. 
Changes the number of bytes allocated to a file. 


Determine or set the verify option when writing to the 
disk. 


Sets up a search path for a program. Supersedes 


the OS/2 DPath command. 


This group of functions is used together to search a 
directory for occurrences of file names or subdirectories. 


Renames a file and/or moves it to another directory. 


Deletes a file. 
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Disk Management Functions 


In this version of OS/2 the logical format of the disk is exactly the same as in 
DOS. This eliminates the need for data conversion when migrating from DOS to 
OS/2. But, as explained earlier, the DOS disk format was designed for a single- 
tasking system, making multitasking disk I/O access inefficient. Future versions of 
OS/2 will probably allow the user to choose between the old DOS format, and a 
new format designed especially for a multitasking system. 

This chapter does not contain a detailed description of the DOS disk format 
because in a multitasking environment, where many files are being accessed by the 
operating system and other running applications, any attempt to manipulate the 
FAT and other operating system-specific disk areas might have disastrous conse- 
quences. A mild example of this would be an application sorting all the files on a 
disk by rearranging the FAT entries. If, prior to this, the operating system had 
opened a number of files as dynamic link libraries, the operating system would not 
be aware of any changes made in the order of the FAT entries by the other program. 
Therefore, when the operating system attempts to read from these files, it looks for 
them in their old positions in the FAT table. The operating system loads the wrong 
data into memory causing the system to crash. There are many scenarios where the 
manipulation of FAT entries in a multitasking system could ruin the data on the 
drives. This is why the user should use the appropriate OS/2 utility instead of 
implementing one of his or her own when undeleting files or restoring lost data. 

Because of these difficulties, direct I/O services to the disk drive are not 
provided as part of the OS/2 API functions. However, an OS/2 application can use 
IOCTL functions to read and write to disks on the sector level. IOCTL functions 
are discussed in Chapter 18. | 

OS/2 provides only a few functions for disk management. DosQCurDisk 
returns the current default disk, and other information about all the drives 
attached to the system; DosSelectDisk changes the default disk drive. DosPhysi- 
calDisk provides information on how the hard drive is partitioned. DosQFSInfo 
returns information about the file system for the disk, the disk volume label, the 
total number of sectors which it contains, and the number of bytes per sector. The 
complementary function DosSetkSInfo changes the volume label of a disk. 
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Logical Drive Map, Default Drive, DosQCurDisk, andDosSe- 
lectDisk 


DosQCurDisk queries OS/2 for the current default disk drive for the calling 
program and returns to it the current default drive number. Drive A: is indicated 
with a value of one (1), drive C: is indicated with a value of three (3), and so on. 
The function DosSelectDisk changes its current default drive. Because OS/2 is a 
multitasking system, each program can specify which drive(s) it will use. 

DosQCurDisk also returns a drive map which indicates the number of logical 
drives currently installed on the system. A logical drive can be one of a number of 
diskette drives or the hard drives installed on the system. It can also be a hard drive 
partition, a network drive set-up by the network program, or the hard drive of 
another computer made accessible to the current system through a communica- 
tion program. These types of logical drives are also considered to be part of the 
system, even though they are connected through software, and are not physically 
connected. Direct disk I/O or DASD access is not usually allowed for logical drives 
connected in this manner. 

The drive map is returned by a pointer LogicalDriveMap which points to a 32-bit 
or long variable. Each bit from 0 to bit 25 indicates the presence or absence of a 
logical drive, which is represented by the letters A to Z. Bits 26 to 31 in this variable 
are meaningless. Ifa specified bit is set, this indicates that the logical drive exists. 
For example, a typical system will have bits 0-2 on and the rest of the bits off. This 
indicates that drives A, B, and Care installed on the system and no drive letter above 
C exists. 


DosQCurDisk (DriveNumber, LogicalDriveMap) 


unsigned far *DriveNumber; /* pointer to which the drive number is 
returned* / 


long far *LogicalDriveMap; /* pointer to the drive map variable */ 
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Example 


/*Q CURDISK.C 
/* this program demonstrates how to use DosQCurDisk */ 


/jfdefine DRIVEA 0x0001 
/ifdefine DRIVEB 0x0002 
/i#define DRIVEC 0x0004 
/itdefine DRIVED 0x0008 
/itdefine DRIVEE 0x0010 


/#tdefine LOWORD(1) (Cine) (15) 
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#tdefine HIWORD(1) ((int) (((long) (1) >> 16) & OxFFFF)) 
include <doscalls.h> 
include <stdio.h> 


main () { 
unsigned DriveNumber; /* default driva number */ 
unsigned long LogicalDriveMap; /* bit-mapped value of 
ad: ey 


/* possible logical 
drivyas */ 
unsigned ret; 
ret= DOSQCURDISK( (unsigned far *)&DriveNumber, 
(long far *)&LogicalDriveMap) ; 
i? Cret) 4 
srinti ("\nDes@Gurbiek failed da”, ret} : 
DOSEXIT (1.0) 
} 
prantt(*\nDetault Drive: 
mc”, (char) (DriveNumbert+(unsigned)’A’ - 1)); 
/* in order to determine whether the drive is available. We 
need to test for each individual bit from bit 0 - 25 of the 
variable LogicalDriveMap. We will only test for drives A to E 
in this case. That is why we’re only concerned with the lower 
word of the variable, */ 


if ((LOWORD(LogicalDriveMap) & DRIVEA) == DRIVEA) 
printf(“*\nDrive A is available”); 

else 
printf(“\nDrive A is not available”); 


if ((LOWORD(LogicalDriveMap) & DRIVEB) == DRIVEB) 
printf(“\nDrive B is available”) ; 

else 
printf(“\nDrive B is not available”); 


if ((LOWORD(LogicalDriveMap) & DRIVEC) == DRIVEC) 
Orintr(”\nDrive Cis available”); 

else 
printf(“\nDrive C is not available”) ; 


if ((LOWORD(LogicalDriveMap) & DRIVED) == DRIVED) 
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printf(“\nDrive D is available”); 


else 
printft(“\nDrive Dis not available”) ; 

if ((LOWORD(LogicalDriveMap) & DRIVEE) == DRIVEE) 
printf(“\nDrive E is available”); 

else 


printf(“\nDrive E is not available”) ; 


DosSelectDisk (DriveNumber) 


unsigned DriveNumber; /* drive number to be selected */ 





Disk Parameters 


Under OS/2 a hard drive can be divided into multiple disk partitions or 
volumes. The term volume is taken from the vocabulary of mainframe environ- 
ments where a tape or diskette—a volume—is mounted for I/O and dismounted 
when no longer needed. In the OS/2 environment, the term volume refers to the 
practice of dividing a single larger physical disk into several logical drives. Each 
volume is accessed as if it were an actual separate physical drive. Each volume is 
also called a disk partition, and each disk partition is limited to a maximum size of 
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32 Megabytes. Versions of DOS before 3.3 do not support the disk partitioning 
concept (which only applies to hard disks; diskettes are always a single volume). 

Each logical drive is divided into multiple allocation units or clusters which are 
further divided into sectors. Each sector stores a specified number of bytes of data 
depending of the type on disk drive. 

All disks including floppy diskettes are identified by a volume label which is used 
to determine whether the diskette has been removed from the drive. For 
removable media like diskettes the volume name prevents many system problems. 
For example, when a program is intermittently writing to a file on a diskette, and 
the diskette is removed and a new one is put in. Before continuing writing, a 
verification of the volume label is necessary to insure that the intended target 
diskette is still in the drive. This prevents the program from writing to the wrong 
diskette, damaging data on it. 

Each disk, including floppy diskettes, can be identified with a volume label. The 
volume label is not useful for disk drives that use nonremovable media like hard 
drives. Butin diskette drives, assigning a unique volume label can help prevent the 
accidental loss of important data. This is particularly important in a multitasking 
system where a program might be interrupted by the operating system before it 
finishes writing to a disk. During this interruption if the user accidently changes 
disks there could be disastrous consequences. The program would simply write to 
a sector on the new disk calculated from information obtained from the old disk. 
Providing a unique volume name for each diskette prevents this from happening, 
because OS/2 always checks to see whether the volume label of a diskette has 
changed when a write operation that was interrupted is to resume. This verifica- 
tion of the volume label assures that the previous diskette is still in the drive. If the 
volume label has been changed since a program’s last disk access OS/2 prompts 
the user for the correct one. 

In addition to the user specified volume name, each disk prepared with the OS/ 
2 FORMAT command is marked with a 32-bit random number which is placed in 
the boot sector of the diskette. This is called the the volume id field. OS/2 
modules check this field before they perform I/0 resulting in fewer disk operations 
needed when identifying media. However, application programs should use the 
the 1 1-byte volume label discussed above to provide a meaningful name to the user. 
Disks formatted under DOS do not receive the volume ID field in their boot sector, 
so diskettes meant to be run under OS/2 should be formatted from a protected 
mode session whenever possible. 


DosQFSiInfo and DosSetFSInfo 


DosQFSInfo returns information on the characteristics of a disk drive or disk, 
or the volume label for the disk contained in a disk drive. It returns the file system 
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ID', the number of sectors per cluster, the total number of clusters contained by 
the drive, the number of sectors available for storage, and the number of bytes per 
sector. Volume information simply consists of the volume label string. OS/2 only 
allows an 11-byte volume label. 

DosQFSInfo expects the drive number of the logical drive which is being 
queried (DrveNumber), the type of file system information requested, either drive 
or volume info, (FS/nfoLevel), a pointer to a data structure where this information 
will be returned (/S/nfoBu/f), and the length of this data structure (FS/nfoBufSize). 
A DriveNumber specification of 1 refers to the drive A:, 3, refers to drive C:, etc. The 
parameter, DriveNumber can also have a value of 0 indicating the curent default 
drive. The data structure for this buffer varies depending on the kind of file system 
(FS) information being requested. If the /S/nfoLevel parameter is set to 1, the 
function returns information on the drive. If it is set to 2, volume information is 
returned. 

If the requested FS information is level 1, or drive information, the data 
structure for /S/nfoBuf must follow this format: 


struct FSinfo { 


lene tileye_ID: /* file system ID */ 

long sec_per_unit; /* number of sectors in one 
cluster */ 

lone num wnite: /* total number of clusters on 
the disk */ 

long avail_units; /* pumber of clusters available 
for storage */ 

unsigned bytes_sec; /* number of bytes per 


sector */ 
From this information, the total disk space can be calculated using the formula: 
disk space = bytes_sector * sector_per_cluster * number_cluster 
The available disk space can be calculated using the following formula: 
available disk space = bytes_sector * sector_per_cluster * avail_cluster 


If the information request is for volume, or level two information, the data 
structure for FS/nfoBuf has this format: 


' The file system ID identifies the file structure system that is in effect for the current disk. The current 
version of OS/2 only supports the DOS file system. In the future this parameter will be used to differentiate 
among different file systems. 
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struct Vol_Info { 


unsigned CreateDate; /* creation date of volume 
label */ 

unsigned CreateTime; /* creation time of volume 
label*/ 

char length; /* length of volume labled, not 
ine Luding NULL *y 

char volume[14]:; /* volume label ASCIIZ 


Biro. *7 


ie 


The fields CreateDate and CreateTime return the creation date and time of the 
volume. The creation date information is in the form day (1-31), month (1-12), 
and year (0-119). The range of the value for year represents the year from 1980 
to 2099, with a value of 1 representing the year 1981. The CreatDaie field is a bit- 
mapped value with the format: 





The creation time information consists of the hour (0-23), minute (0-59), and 
second when the file was created. CreateTime stores this information as a bit- 
mapped value with the following format: 





25 bits can only represent a value from 0 to 32. 


Disk, Directory, and File Management 427 


The program must provide the length of the string char volume to which the 
volume label will be written using the char length field of the data structure. This 
value should be large enough to accommodate the actual length of the volume 
label string returned by OS/2. This string should have a length of 12 bytes, and 
char length should specify the same. Then the buffer can contain the 11 bytes of 
the volume label string plus one null byte. Ifa smaller value is defined, the function 
tries to fit the label string into the buffer provided. For example, if three bytes are 
specified as the length of the volume label string, OS/2 only returns the first three 
bytes of the string. Future versions of OS/2 that support longer volume labels will 
require a proportionately larger buffer. 

The size of the data structure for disk information is 18 bytes. The buffer size 
for level one information is 18 bytes and for level two is 17 bytes. 

DosSetF'SInfo changes the volume label of a disk. The parameters required by 
the function are the same as for DosQF'sInfo. For DosSetFSInfo, the parameter 
FSInfoLevel can only have a value of two (2), specifying that volume information is 
to be changed, because it is not possible to change the disk statistics. Instead of 
returning the volume information to the buffer, /S/nfoBuf, an ASCIIZ string stored 
in this buffer modifies the volume label of the drive. The size of the buffer is 
dependent on the length of the new volume label. Remember that a volume label 
is limited to 11 bytes. Any string longer than this is truncated to fit into the 11-byte 
restriction. 


DosQFsinfo (DriveNumber, FSinfoLevel, FSinfoBuf, FSinfoBufSize) 


DosSetFsInfo (DriveNumber, FSinfoLevel, FSinfoBuf, FSinfoBufSize) 


unsigned DriveNumber; /* logical drive number */ 
unsigned FSInfoLevel; /* type of information requested */ 
char far *FSInfoBuf; /* buffer containing returned 


information */ 
unsigned FSInfoBufSize; /* length of the buffer */ 
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Example 
/* QFSINFO.C 


This program demonstrate how to use DosQFSInfo and DosSetFSInfo. 


This program will call DosQCurDisk to determine the current 
default drive number then call DosQFSInfo for both level 1 and 
level 2 info, it displays them then asks the user for a new 
volume label and changes the current volume label. 


at | 
include <doscalls.h> 
include <stdio.h> 


struct FSlntoe | 
long filsys_ID; /*- file eyeten ID */ 
long sec_per_unit; /* sectors per cluster */ 


long num_units; 
long avail_units; 
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/* total clusters */ 
/* available clusters */ 


unsigned bytes_sec; /* bytes per eactor */ 


struct Vol_Inifo { 
unsigned CreateDate; 
unsigned CreateTime; 
char length; 


char volume[14]; 


struct Set_Label { 
char length; 


char volume[14]: 


i 


#tdefine LEVEL] if /* file system information level */ 
4Kdefine LEVEL2 2 
+#define ERROR NO VOLUME LABEL 125 /* no volume label found */ 
define HIBYTE(w) (((unsigned) (w) >> 8) & Oxff) 
4tdefine DAY(d) (d & Ox001F) 
+#define MONTH(d) (d >> 5 & 0x0007) 
+#define YEAR(d) (1980+(d >>9 & Ox007F)) 
+#define HOUR(t) (= >> 11 & Ox001F) 
+#define MINUTE(t) (t >> 5 & Ox003F) 
+#define SECOND (t) (2 *(t & OxO00F)) 
main {) { 
unsigned DriveNumber ; /* default drive number */ 


unsigned long LogicalDriveMap; /* bit-mapped value of */ 


unsigned ret; 


unsigned length; 


/* all possible logical. 
drives */ 
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char s[100]; 


/* perameters for DosSetPSiInfo */ 


unsigned FSInfoBufSize; /* leneth of burfer */ 
struct FsiInro fsinfo; 
Struct Volare volini a: 


struct Set Label iabel: 
/* determine the current disk drive */ 


ret= DOSQCURDISK( (unsigned far *)&DriveNumber, 
(long far *)&LogicaliDriveMap) ; 
TF (ret) J 
printt(* \nbosQCurbDiek failed %d”“, fet): 
DOSEXIT(1,0) ; 
} 


/* getting file system level 1 information */ 


ret = DOSQFSINFO(DriveNumber, LEVELI, . 
(char far *“)&éfeinfio, sizeol (etruet FSInfoe)) : 


if (ret) { 
printf(“\nDosQFSInfo level 1 failed %d”,ret); 
DOSEAIT (1,0) 3 


Aminer (a Pile System ID : “Sid”. fsinfo,fileys_ID) > 

ep apie yrck Gaal al SectorClueter < la” ,fsinfo. sec per wit); 

printt (*\A Bytes/Sector + %d”,fsinfo.bytes_sec) ; 

eriner Uo Total Cluster on Drive : %1ld”, 
feito un units) : 

printf(“\n Unused Clusters: tld” ,fsinto.avail units); 


i* gattine file system level 2 information */ 
/* en error of 125 is retitirned if no volume label is 
defined */ 


ret = DOSQFSINFO(DriveNumber, LEVEL2, 
(char far *)évolinfio, sizeot (struct Vol_Intfo)) ; 
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1€ ({lret) | 
printf(“\n\nVolume Label: %s”,volinfo.volume) ; 


/* display create date and-time */ 

/* refer to discussion in the book for the bit-map of 
the parameters: 

CreateDate and CreateTime 


at 
printf(“\n Create Date: %02d/%02d/%04d”", 
MONTH (volinfo.CreateDate), :* monn: OF 
DAY (volinfo.CreateDate) , ce day *y 
YEAR(volinfo.CreateDate) ): f* wear * 
Horintt(“\n. Create Timer %02d:%02d: 02d", 
HOUR (volinfo.CreateTime) , 
MINUTE (volinfo.CreateTime) , 
SECOND (volinto,CreateTime) ); 
} else if (ret == ERROR NO VOLUME LABEL) 
printf(“\nNo volume label for drive %e”, 
(char) (DriveNumbert+(unsigned)’A’-1)); 
else 
printf(“\nDosQFSInfo level 2 failed %d”,ret): 
while (1) { 


printf(“\n\n(Volume label must be less than 11 
characters)”); 

printr(" \n Please enter new volume label: “); 

gatsla)s 


length = strlen(s); 
if (length <= 11 && length > 0) { 
strepy(label.volume,s); 
label.length = (char)length; 
ret = DOSSETFSINFO(DriveNumber, LEVEL2, 
(char far *)&label, 
sizeof (struct Set_Label)):; 
if (ret) 4 
printf (“\nDosSetlSinfo failed %d”, ret) ; 
DOSEZIT(1,0): 
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break: 


ret = DOSQFSINFO(DriveNumber, LEVEL?2, 
(char far *)&wolinfs, 
gizeot {struct Vol. Into) }: 


it (leery 4 
printf(“\n\nNew Volume Label: %s”,volinfo.volume) ; 
printf (“\n Create Date: %02d/%02a/%04d" , 


MONTH (volinfo.CreateDate), J” mont * 7 
DAY (volinfo.CreateDate), i? dag */ 
YEAR (volinfo.CreateDate) ); L* vee Sy 


printt(“\n Create Time: %O2d:%02d -402d" , 
HOUR(volinfo.CreateTime) , 
MINUTE(volinfo.CreateTime) , 

SECOND (volinfo.CreateTime) ): 


} else if (ret == ERROR NO VOLUME LABEL) 
printf(“\nNo volume label for drive %c”, 
(char) (DriveNumbert+(unsigned)’A’-1)); 
else 
printf" \nDesOFSinfo level 2 failed %d”,ret) ; 
DOSEXIT (1,0): 


Disk Partitions and DosPhysicalDisk 


DosPhysicalDisk determines the number of disk partitions on the current hard 
drive. The function also obtains or releases a handle for a disk which 1s used for 
direct disk I/O supported by the IOCTL category nine function calls. This handle 
cannot be used with file I/O API functions such as DosRead and DosWrite. We 
discuss the IOCTL functions in Chapter 18. 

DosPhysicalDisk expects the type of function requested (function), a pointer to 
a buffer where the returned information will be stored (DataPir), the length of the 
buffer (DatLen), a pointer to a buffer where the parameters provided by the 
program are stored (ParmPir), and the length of the parameter buffer (ParmLen). 

Since DosPhysicalDisk can be used to perform three different functions, the 
parameter function specifies which is to be performed. The nature of the 
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information returned in function, and the parameters that must be specified by the 
calling program, vary according to the function chosen. 


DosPhysicalDisk (Function, DataPtr, DataLen, ParmPtr, ParmLen) 


unsigned Function; /* value indicating type of request 
function */ 

char far *DataPtr; /* pointer to returned information 
buffer */ 

unsigned DataLen; /* length of the buffer */ 

char far *ParmPtr; /* pointer to input information buffer */ 


unsigned ParmLen; /* length of input buffer */ 
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Example 
/* PHYSDISK.C 


This program demonstrate the capabilities of function DosPhysi- 


calDisk. 
= 


#Finclude <stdio.h> 
include <doscalls.h> 


#tdefine DISKPARTITION 1 /* request functions */ 
4t}define REQHANDLE p: 
4tdefine RELEASEHANDLE 3 


ttdefine NULL 0 


char drive[5]="1:”; /* ask for first partitionable drive */ 


/* this would be drive @: */ 


main () 

| 
unsigned NumberOfPartition; /* option 1 */ 
unsigned DriveHandle; /* option 2 */ 


unsigned ret; 

/* request Tor particion */ 

ret = DOSPHYSICALDISK (DISKPARTITION, 
(char far *)&NumberOfPartition, 
sizeof (NumberOfPartition) , 
(char far *)NULL, 
Oy 


if (ret) 
printf (“\nDosPhysicalDisk failed: %d”,ret): 
else 
printf(“\nNumber of Partitionable disks: %d”, 
NumberOfPartition) ; 


DriveHandle = 0; /* request for partition */ 
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ret = DOSPHYSICALDISK (REQHANDLE, 
(char far *)&DriveHandle, 
sizeof (DriveHandle) , 
(ehar far *)drive, 
strien(drive)+1) ; 


it (recy 4 
printf(“\nDosPhysicalDisk request handle failed:%d”,ret) ; 
DOSEXIT(1,0); 


printf(“\nDrive Handle %d”,DriveHandle) ; 


/* At this point, we can use Device IOCTL category 9 


functions */ | 
/* to access the physical drive */ 


ret = DOSPHYSICALDISK (RELEASEHANDLE, 
(char far *) NULL, 
0, 
(char far *)&DriveHandle, 
sizeof (DriveHandle) ) ; 
if (ret) 
printf(“\nRelease handle failed: %d”,ret); 
else 
printf(“\nHandle was released”) ; 


DOSEXIT(1,0); 


Directory Management Functions 


The storage space on a hard disk drive is usually divided into subdirectories to 
manage files more efficiently. This is not usually done with diskettes where size 
constraints dictate that all files be stored on the same directory. Ona hard drive, 
files are divided among various subdirectories, grouping them for convenience or 
protection. For example, utility programs are usually stored on the same directory. 
In C the compiler may be stored in one directory, while object files, source files, 
and library files may be stored in different subdirectories. The arrangement of 
subdirectories on a disk is said to have a a tree structure, with subdirectories 
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branching out from parent directories. The first directory, or the directory at the 
top of the tree structure is called the root directory (See Figure 11.1). 

When specifying the name of a file, a path name to that file must be provided, 
so that the operating system knows where to find it. To take an example from 
Figure 11.1, in order to execute the file go.bat in the subdirectory BAT, from the 
root directory, one would have to enter \Bat\go. In order to execute the file 
myprog.c (see illustration) one would have to enter \cc\exe\myprog.c. The 
information which specifies which subdirectory a file resides in is called the path. 
Itis also possible to instruct the operating system to assign a directory as the current 
directory. For example one can specify that the \BAT directory be the current 
directory. In this case any files in the current directory can be accessed without the 
path. 

OS/2 provides API functions that allow directories to be manipulated. The 
functions discussed in this chapter can be used within a program, or can be entered 
by the user directly from the command line. In either case the results will be the 
same, only the format of the call will be different. However, this section will 
describe those API which allows the program to determine the current directory 
name?* to change directories, as well as creating and removing directories from the 
drive. 


Filenam1.ext 
Filenam2.ext 


c:\childb 


Filenam1.ext Filenam1.ext 
Filenam2.ext Filenam2.ext 
etc.. 


c:\childa\gchilda c:\childa\gchildb c:\childa\gchildc 


Filenam1.ext Filenam1.ext Filenam1.ext 
Filenam2.ext Filenam2.ext Filenam2.ext 
etc.. etc.. etc.. 





Figure 11.1 Tree-Structured Directory. 


3 A directory name is similar to a file name with a limit of 8 characters for the name and 3 characters for the 
extension. Please see Chapter 6 for more information about the naming conventions of file and directory. 
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DosQCurDir—Get Current Directory 


The function DosQCurDir returns the current default directory for a program 
on a particular drive. This is the same as the the CD command. The name is 
returned as an ASCIIZ string and includes a full directory path starting from the 
root directory, but does not include the drive letter or a leading back-slash (\). If 
the current directory is the root directory, a null-string is returned. The current 
drive can be determined using DosQCurDisk. 

DosQCurDir expects the drive number, a buffer in which to return the directory 
path, and the byte length of the buffer. The logical drive number indicates the 
logical drive where the program wants to determine the default directory; it does 
not necessarily have to be the default drive. A full directory path can sometimes 
be quite long, especially when there are subdirectories within subdirectories. ‘To 
make sure that the buffer can handle the complete path, it should be 64 bytes long, 
the longest path name the system can handle. 


DosQCurDir (DriveNumber, DirPath, DirPathLen) 


unsigned DriveNumber; /* logical drive number */ 


char far *DirPath; /* pointer to buffer where directory path 
is returned */ 


unsigned DirPathLen; /* length of the buffer in number of bytes */ 
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DosChDir—Change Directory 


DosChDir changes the current directory on a specified drive or the default drive 
to anew directory. It works in the same way as the OS/2 CHDIR or CD command. 
DosChDir expects an ASCIIZ string containing the new directory path. The 
chosen directory becomes the default directory, so any files in it can be accessed 
without a path name. If the new directory is on a different drive the string should 
include the drive letter and colon. If no drive name is included, the current drive 
is assumed. The longest directory path that OS/2 can handle is 64 bytes. The 
system will not switch to the new subdirectory if the name specified is invalid or 
does not exist. 


DosChDir (DirPath) 


char far *DirPath; /* pointer to the new default directory 
path */ 





DosMkDir—Create Subdirectory 


DosMkDir creates a new subdirectory. (This function expects the same parame- 
ters and provides the same services as the OS/2 MKDIR or MDIR command.) It 
expects an ASCIIZ string containing the full directory name, and its path. Ifa drive 
name is included, it creates the subdirectory on the specified drive, otherwise, it 
assumes the default drive. A full path to the directory is recommended, but not 
necessary. A simple subdirectory name without any directory path is valid, because 
the system creates the new subdirectory branching from the current default 
directory. If any directory name specified in the path does not exist or is invalid, 
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no subdirectory will be created. Finally if a subdirectory with the same name and 
with the same path already exists, no subdirectory will be created. The full 
directory path cannot exceed 64 bytes. 


DosMkDir (DirPath) 


char far *DirPath; /* pointer to the new subdirectory 
path */ 





DosRmDir—Remove Subdirectory 


DosRmDir removes or deletes a subdirectory. (This function expects the same 
parameters and provides the same services as the OS/2 command RMDIR or RM.) 
It expects an ASCIIZ string containing the full directory name. Ifa drive name is 
included, the subdirectory is removed from the specified drive. Otherwise the 
system assumes the default drive. A full directory name is recommended but not 
necessary. A simple subdirectory name without any reference to the previous 
directory path is valid, because the system will remove the subdirectory if it 
branches from the current default directory. If any directory name specified in the 
path does not exist or is invalid, no subdirectory will be removed. The full directory 
path cannot exceed 64 bytes. Finally, only an empty subdirectory (one containing 
no files) can be removed. 


DosRmDir (DirPath) 


char far *DirPath; /* pointer to the new subdirectory 
path */ 
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Examples 
/* QDIR.C 


This program demonstrates how to use: 
DosQCurDir 
DosRmDir 
DosMkDir 
DosChDir 
af 


include <stdio.h> 
include <doscalls.h> 


/* Values for execution mode, Execmode*/ 


define SYNC 0 /* Synchronous execution */ 
ffdefine ASYNC 1 /* Asynchronous execution */ 
#tdefine ASYNC_RES 2 /* Same ag 1, result codas is returned */ 
#fdefine NULL 0 
main {) 
{ 
unsigned DriveNumber; /* default drive number’ */ 


unsigned long LogicalDriveMap;/* bit-mapped value of */ 
/* ell psossibie 
logical drives */ 
ehar DirPath(64|, temp [64] ; 
unsigned DirLen; 


struct ResultCodes RetCode; /* Reswit Codes */ 
unsigned ret; 


DirLen — 64; /* mee defatilt drive for drive numbar */ 
ret = DOSOCURDIR(0;, (char far *)DirPath, 
(unsigned far *)&DirlLen) ; 


if (ret) | 
printf(“\nDosQCurDir failed %d”,ret); 
DOSEXIT (1,0); 


Disk, Directory, and File Management 443 


printf(“\nCurrent Directory: %s. Notice how there’s no \\ 
before the value”,DirPath) ; 


printf(“\n\nMaking a subdirectory called TEST”); 
ret = DOSMKDIR( (char far *)*TEST”, OL); 


if (ret) { 
printf(“\nDosMkDir failed %d”,ret); 
DOSEXIT (1,0); 


printit(*\naSwiteh to TEST subdirectory”) : 
ret = DOSCHDIR( (char far *)”"TEST”, GL); 
if (ret) { 
printf (*\nDosChDir failed %d”,ret); 
DOSEXIT (1, ©) : 


strepy (temp, ”\\"): 

streat (temp,DirPath); 
printt(“\nSwiteh back to %s*,temp): 
ret = DOSCHDIR( (cher far *)/temp, OL): 


i= (ret) { 
printf(“\nDosChDir failed %d”,ret) ; 
DOSCHDIRitehar far *)"..” ,OL); 


} 
printf(“\nRemove TEST subdirectory”) ; 
streat (temp, ” TEST”): 


ret = DOSRMDIR( (char far *)temp, OL): 
if (ret) 


printt(*\nDoskmDir failed %d* rer): 
DOSESTT (1,0): 
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File Management Functions 


In the previous chapter we learned how programs open and close files and 
perform file I/O. In this section we present functions that manipulate files as a 
class. We discuss functions determining and manipulating the status of a file, 
setting up a search path, searching fora file, moving a file to another directory, and 
deleting a file. 


File Status Functions 


Three types of status information are maintained for a file. They are: the file 
attributes, the file opening mode or state*, and general file information such as 
date and time of creation, file verification status, and file handle type. The file 
attributes and related information are stored in a single directory entry on the 
directory sector located on the drive. Each directory entry is a data structure 
containing the file name, extension, attribute, time and date of creation and last 
update, starting cluster and file size. The file opening state information is 
generated whenever a file is opened for access, and is maintained for as long as the 
file remains open. 

Except for the starting cluster, all of this information can be manipulated using 
OS/2 API functions. DosQFileInfo and DosSetFileInfo can be used to determine 
and to set the creation and update times and dates for a file. The file attributes are 
determined and changed using DosQFileMode and DosSetFileMode. The file size 
can be changed using DosNewSize. The function DosQFHandState determines 
whether an opened file handle specifies a device or a file. The functions 
DosQFHandState and DosSetHandState determine and set the opening state of a 
file handle. The file state includes the inheritance flag, file buffering option, and 
error handling option. Please refer to Chapter 10 for more details on the opening 
state of a file. 

The file verification option specifies whether writing operations to a file will be 
verified by the operating system. If the verification option has been chosen the 
operating system automatically reads the data from the disk every time it writes to 
the file to ensure that the data has been correctly output. Unless there are 
problems with the hard drive, such errors rarely occur. The verification option 1s 
provided for applications that rely on failsafe data. Verification, however, slows 
down the system because every write operation is accompanied by a corresponding 
read operation, and should be use sparingly. The functions DosQVerify and 


* See Chapter 10 for information on these two topics. 
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DosSetVerify determine and set the verification option of the current program, 
respectively. 


DosQFHandState 


The function DosQFHandState determines the file opening state of a currently 
opened file. ‘The file must have been opened with function DosOpen, and the file 
handle returned with that function must be supplied. DosQFHandState simply 
returns the value of the parameter OpenMode passed to DosOpen when the file was 
opened. The file opening state consists of the following options: access mode, 
share mode, inheritance flag, file buffering option, and DASD option. The file 
opening state is returned in a 2-byte (WORD) or unsigned bit-mask value specified 
by the variable F2leHandleState. 


DosQFHandState (FileHandle, FileHandleState) 


unsigned FileHandle; /* file handle of the opened file */ 


unsigned far *FileHandleState; /* returned file opening state */ 
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Example 


/* QFHSTATE,C 
This program demonstrates how to use DosQFHandState and Dos- 
SetFHandState. 


«if 
include “doscalls.h” 


define MASK Ox/Frse 7* all bits not weed by 
SetFHState */ 


#fdefine INHERIT Oxh0s0 /* thharitance flag set */ 
##tdefine ERRHANDLING 0x2000 /* error handling flag set */ 
##tdefine BUFOPTION Ox4000 /* write-through fleas seat */ 


+#define NORMAL Ox0000 /* normal file attribute */ 
+#define O FAIL Ox0000 /* constant for DosOpen */ 
define O OPEN Ox0001 /* and for DosQFHandState */ 


4tdefine O REPLACE 0x0002 
+#define O CREAT Ox0010 /* create af file not exiets */ 
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#tdefine DENY_READ Ox0010 /* sharing mode */ 
dKdefine DENY WRITE 0x0020 
4edefine DENY NONE 0x0040 


+tdefine READ ONLY Ox0000 /* access mode */ 
4tdefine WRITE ONLY 0Ox0001 
4define READ WRITE 0x0002 


adh () 


{ 


unsigned Handle; 
unsigned ActionTaken; 
unsigned FHandState; 


unsigned ret; 


ret = DOSOPEN( “TEST .DAT”, 
(unsigned far *)&Handle, 
(unsigned far *)&ActionTaken, 
OL, 
ie 
O_CREAT | O_OPEN, /* open file if exists, */ 
/* alge eréates */ 
DENY_NONE | READ_ONLY, 
OL) ; 


tf Cree) 4 
printt (“\nDosOpen failed %d”,ret) ; 
DOSEXIT(1,0): 


ret = DOSQFHANDSTATE (Handle, (unsigned far *)&FHandState) ; 


Le iret). 4 
printzt (“\nDoeQFHandState failed %d”,ret): 


DOSEXIT(I,0) : 
} 


printf(“\nFile Handle State %04x”,FHandState) ; 


/* switch the flags te Child Inherit, No Buffering */ 


448 Advanced Programmer's Guide to OS/2 


FHandState &= MASK; /* elear all bite not uged by 
fiherioh *7 


FHandState |= (INHERIT | BUFOPTION) ; 
printf(“\nSet File Handle State to : %04x”,FHandState) ; 
ret = DOSSETFHANDSTATE (Handle, FHandState); 
if (ret) 
printf ("\nDosSetFHandState failed %d",ret) : 


ret = DOSQFHANDSTATE (Handle, (unsigned far *)&FHandState) ; 
Lf {ret} 1 
printf(“\nDosQFHandState failed %04d”,ret); 
DOSEXIT(1,0); 
printf(“\nGet New File Handle State %04x”,FHandState) ; 


DOSCLOSE (Handle) ; 


DOSEXIT (1,0); 


DosSetFHandState 


The function DosSetFHandState changes the file opening state of a currently 
opened file. The file must have been opened with the function DosOpen, and the 
file handle returned by that function must be supplied. DosSetHandState changes 
the value of the parameter OpenMode passed to DosOpen. Because of certain 
restrictions imposed by OS/2, only the following opening states can be changed: 
the inheritance flag, the file buffering option’, and the error handling option®. A 
2-byte (unsigned or WORD) bit-mask variable, FileHandleState, is used to contain 
all these options. 


DosSetHandState (FileHandle, FileHandleState) 


unsigned FileHandle; /* file handle of the opened file */ 


unsigned FileHandleState; /* new file opening state */ 


*The OS/2 Technical Reference calls this bit the File Wrte-Through flag. 
*This option is referred to as the Fail-Error bit by the OS/2 Technical Reference. 
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DosQHandType 


Function DosQHandType informs a program whether a specified file handle 
represents a file, a device, or a pipe. It is very useful for a child process to be able 
to determine what type of device or resource an inherited file handle represents. 
For example, a child process could use this function to determine that it had 
inherited a file, instead of the keyboard, as its standard input device, and would not 
ask for user input. For more information on child processes and resource 
inheritance, please refer to Chapter 2. The function also returns the attribute 
word associated with a character device. The attribute word is used by device 
drivers to monitor the status of devices (consult the IBM Device Driver Manual for 
more information). 

DosQHandType expects the file handle (/2leHandle), a pointer to a 2-byte 
structure where the handle type is returned (HandType), and another pointer to 
a 2-byte value where the attribute word for a character device will be returned 
(flagWord). ‘The file handle can be inherited by the process or obtained using 
DosOpen or DosMakePipe. | 

The structure of the 2-byte returned handle type variable is as follows: 


struct HandType { 
char HandleBite: 
ehar HandleGlass: 
} 


The HandleClass field of this data structure represents the type of device that the 
handle represents. 

The HandleBits field of the data structure is also an 8-bit value. Bits 0 through 
6 are reserved for future usage. Only bit 7 currently has any meaning. It 
determines whether the device is a network device or not. If bit 7 is set, the specified 
device is a remote device connected to the system with software, not a device 
physically installed on the system such as a disk drive, or a communication port. 
Programs should not make use of bits 0 through 6, because they may become 
significant under future versions of OS/2. 


DosQHandType (FileHandle, HandType, FlagWord) 


unsigned FileHandle; /* the handle whose type is to be 
determined */ 


struct HandType far *“HandType; /* pointer to the returned handle type 
information */ 


unsigned far *FlagWord; /* a pointer to the attribute word of the 
character device */ 
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Example 


/* QHTYPE.C 


this program demonstrates how to use DosQHandType to determine 
the type of file that is opened. 


Py 


include “doscalls.h” 
#ignelude “etdio. kh” 


+#define NORMAL 0x0000 /* normal file attribute */ 
define O_FAIL 0x0000 /* constant for DosOpen */ 
ttKdefine O_OPEN 0x0001 

tt}define O REPLACE 0x0002 

+#define O CREAT Ox0010 /* creat if file not axists */ 
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+#define 
+#define 
+#define 


+#define 
+#define 
tdefine 


+#define 
define 
+#define 
+#define 


+#define 
+#define 


DENY_READ 0x0010 
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/* sharing mode */ 


DENY_WRITE O0x0020 
DENY_NONE 0x0040 


READ ONLY 0x0000 ce 


Access mode */ 


WRITE_ONLY OxOQOO1 
READ _ WRITE 0Ox0002 


DISK 
DEVICE 
PIPES 


NETWORK 


LOBYTE (w) 
HIBYTE (w) 


struct HandType 


ahar Netrebit: 


Ox0000 
OxO0001 
Ox0002 


/* handle type *s 


Ox8000 


((char) (w) ) 
(((unsigned) (w) >> 8) & Oxff) 


char HandleClass; 


Pe 


void Qtypel); 


main () 


{ 


unsigned ret, 
Handle, 
Handle2, 
ActionTaken; 


unsigned HandleType; 


unsigned DeviceAttrib; /* 


device drive attribute word 


printf(“\nOpen TEST.DAT”) ; 


ret. = 


DOSOPEN(“TEST.DAT”, 


(unsigned far *)&Handle, 
(unsigned far *)&ActionTaken, 
OL, 

0, 


| 
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O_CREAT | O_OPEN, /* open file if exists, */ 
/* else ereates */ 

DENY_NONE | READ_ONLY, 

OL) ; 


if (ret) { 
printf(“\nDosOpen failed %d”,ret); 


DOSEXIT (1,0) : 


ret = DOSQHANDTYPE (Handle, 
(unsigned far *)&HandleType, 
(unsigned far *)&DeviceAttrib) ; 


printf(“\nDevice Attribute: %04X”,DeviceAttrib) ; 
Qtype(HandleType) ; 


Printt tl \ninOven OCCM2+"); 

ret = DOSOPEN (“COM2”, 
(unsigned far *)&Handle2, 
(unsigned far *)&ActionTaken, 


oer 

ay 

O_OPEN, /* open tile fF exists, *7 
DENY_NONE | READ_WRITE, 

OL); 


if (ret) { 
printf (*\nOpen GOM2 failed. Check if COM driver is 


installed %d”,reat) : 
DOSEXZIT(1,@): 


ret = DOSQHANDTYPE (Handle2, 
(unsigned far *)&HandleType, 
(unsigned far *)&DeviceAttrib) ; 


printf(“\nDevice Attribute: %04X”,DeviceAttrib) ; 
Qtype(HandleType) ; 


printf(“\n\nChecking Handle type of STDIN”); 
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STDIN 


yoOLd 
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ret = DOSQHANDTYPE (stdin, 
(unsigned far *)&HandleType, 
(unsigned far *)&DeviceAttrib) ; 


orintt (“\nDeviece Attribute: 204k" ,DeviceAttrib) ; 
Qtype(HandleType) ; 


DOSCLOSE(Handle2) ; 

printf(“\n\nOpen Keyboard”) ; 

ret = DOSOPEN("EEDS”, 
(unsigned far *)&Handle2, 
(unsigned far *)&ActionTaken, 


OL, 

0, 

O_OPEN, /* open file 1f exists, */ 
DENY_NONE | READ_ONLY, 

OL); 


if (ret) { 
~:antf£(“\nOpen KBD failed %d”,ret); 


DOSEXIT(1,0) : 


ret = DOSQHANDTYPE (Handle2, 
(unsigned far *)&HandleType, 
(unsigned far *)&DeviceAttrib) ; 


printf(“\nDevice Attribute: %04X”,DeviceAttrib) ; 


Qtype(HandleType) ; 
printf(“\nNotice the difference handle type reported for 


and KBD”): 
DOSCLOSE (Handle) ; 


DOSCLOSE(Handle2) ; 
DOSEXIT(1,0) : 


Qtype (HandleType) 


unsigned HandleType:; 


( 


static char DName[3][10] = {“DISK”, 
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*DEVIGE” , 
“PIPER }s 
char s[80]; 


sprinti(s,”"Handle Type: %s”, 
DName [LOBYTE(HandleType) ]); 


if (HIBYTE(HandleType) == NETWORK) 
streat(se,” Network”): 
else 
streat(s,” Loveai’) = 
erintEe(” (nye ~s) : 


DosQFilelnfo and DosSetFileinfo 


DosQFileInfo determines, and DosSetFileInfo sets, information associated 
with a file such as the creation time and date, etc. In order to change this 
information using DosSetFileInfo, the file must have been opened with write 
access privilege (mode). Both functions require a file handle (fileHandle) anda 
variable (filelnfoLevel) which specifies the type of information requested or set. 
DosQFileInfo needs a buffer large enough to contain the specified file informa- 
tion. A buffer containing the new file information (/le[nfoBuf) must be specified 
for DosSetFileInfo. The byte size of these buffers (/ileInfoBufSize) is also required. 

The information level variable has probably been set aside in anticipation of 
future versions of OS/2 where there will be more file information to be manipu- 
lated. This version of OS/2 only allows for level 1 information (i.e., FileInfoLevelcan 
only be equal to 1). 

For DosQFileInfo and DosSetFileInfo, the pointer FileInfoBufpoints to a 22-byte 
data structure with the following format: 


struct FileStatus { 
unsigned create_date; /* create date */ 
unsigned create_time; /* create time */ 
unsigned access_date;: /* date of last access */ 
unsigned access_time; /* time of last access */ 


unsigned write_date; /* date of last write */ 
unsigned write_time; /* time of last write */ 
long file size: (* lA. gigas “yf 

long falloc_¢ize: /* file Allocation sige */ 


unsigned attributes: /* file attribute */ 
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Create_dateand create_timespecifies when the file was created. The last access_date 
and access_time specify when the file was last accessed for reading or writing. The 
last write_date and wnite_time specify the last writing to the file. 

The time values consist of the hour (0-23), the minute (0-59), and the second 
(0-59) values. All time variables are bit-mapped values and are composed as 
follows: 





The date values consist of the day (1-31), the month (1-12), and the year (0-119). 
The range of the year value represents the year from 1980 to 2099, with a value of 
1 representing the year 1981. All date variables are bit-mapped values and are 
composed as follows: 





The file size specifies the byte size of the file at the last system update via 
DosClose or DosBufReset. The possible values for the file attribute are described 
in Chapter 10. 

For DosSetFileInfo, the pointer FilelnfoBuf points to a 12-byte data structure 
composed of the following fields: 


erruct Sarkilestatiis { 


unsigned create_date; /* create date */ 
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unsigned create_time; /* create time */ 

unsigned access_date; /* date of last access */ 
unsigned access_time; /* time of last access */ 
unsigned write_date3* /* date of last write */ 
unsigned write_time; /* time of last write */ 


} 


When using DosSetFileInfo, a value of zero in any date and time field indicates 
no change will be made to that field. The buffer for DosSetFileInfo is smaller than 
the buffer for DosQFileInfo, because the rest of the information cannot be set by 
DosSetFileInfo. In order to change the file attribute and file size, the functions 
DosSetFileMode and DosNewSize must be used respectively. 


DosQFilelnfo (FileHandle, FilelnfoLevel, FilelnfoBuf, FilelnfoBufSize) 


DosSetFilelinfo (FileHandle, FilelnfoLevel, FilelnfoBuf, FilelnfoBufSize) 


unsigned FileHandle; /* file handle */ 

unsigned FileInfoLevel; /* level of file information requested or to 
be set */ 

char far *FileInfoBuf; /* pointer to the returned information or */ 


/* new information to be changed to */ 


unsigned FileInfoBufSize; /* size of the above buffer */ 
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Example—DOS File Info 


/* INFO.C 
This program demonstrates how to use DosQFilelInfo 


This program will accept a file name and display information 
about the file. 


at | 

include <doscalls.h> 

+#define NORMAL Ox0000 /* normal file attribute */ 
#tdefine O_FAIL 0x0000 /* eonstaht for DosOper */ 


dHKdefine O OPEN 0x0001 
ttKdefine O REPLACE 0x0002 
+#define O CREAT 0x0010 /* ereate 47 file doesn’t exist */ 


#tdefine DENY_READ 0x0010 /* sharing mode */ 
4edefine DENY WRITE 0x0020 
Ht}define DENY NONE 0x0040 


+#define READ ONLY 0x0000 /* Access mode */ 
define WRITE ONLY 0x0001 
4edefine READ WRITE 0x0002 


ffdefine LOBYTE(w) ((char) (w)) 
#tdefine HIBYTE(w) (((unsigned) (w) >> 8) & Oxff) 
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+#define DAY(d) (d & Ox001F) /*date caleulation macros*/ 
define MONTH(d) (d >> 5 & Ox0007) 
define YEAR(d) (1980+(d >>9 & Ox007F)) 


+#define HOUR(t) (t >> 11 & OxDOLF)/*time calculation macrog*/ 
define MINUTE(t) (t >> 5 & Ox003F) 
ffdefine SECOND(t) (2 *(t & OxOOOF)) 


main (arec¢,argv) 
int arec; 
char *arev||: 


unsigned ret, 
Handle, 
ActionTaken: 


struck Filestatie Filelnie: 
char s[80]; 


it farec 2 1) 
strepy|s,arey (1) i: 

else { 
printt(“\nPlease enter file name: %e") +: 
gets(s); 


ret — DOSOPEN( (char far *)s, /*open tile*/ 
(unsigned far *)&Handle, 
(unsigned far *)&ActionTaken, 
OL, 
oF 
O_OPEN, /* open file if exists, */ 
/* elge ereates */ 
DENY_NONE | READ_ONLY, 
Os) 


4 (fet) 4 
Hrintt("\ndesOpen failed %d", ret) + 
DOSEXIT (1,0) % 
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ret = DOSQFILEINFO (Handle, 
Ls /* tile info level, 
only 1 is available */ 
(char far *)&FileInfo, 
Sizeot (struct FileStatts) ); 
if (ret) 
printf(“*\nDosQFileInfo failed %d”,ret):; 
else { 
printf ("\niInformation about %s”,s); 
orintr (“\nOreate Date: “O2d/%02d/%04d Time: 
HO2G:%OZd:%020” , 


MONTH (FileInfo.create date), 
DAY (Fi leinto.create date), 
YEAR(FileInfo.create_ date), 


HOUR(FileInfo.create time), 
MINUTE (FilelInfo.create time), 
SECOND (Fileinfo.create time) ): 


printf(“\nAccess Date: %02d/%02d/%04d Time: 
U2? B20? 0 20”. 
MONTH (FileInfo.access_date), 
DAY (Paleinfo,.access date). 
YEAR (FileInfo.access date) , 


HOUR(FileInfo.access_ time), 
MINUTE (FileInfo.accesgs_time), 
SECOND(FilelInfo,access time) ): 


printf(“\nLast Modification Date: %02d/%02d/%04d 
Time: *#O2Z0:%02d:2,02c” . 
MONTH (FileInfo.write_date), 
DAY (Filelnfo.write date). 
YEAR (Pileinfo.write date), 


HOUR(FilelInfo.write_time), 
MINUTE (Filelinfo.write time} , 
SECOND (FileInfo.write_time) ); 


printf(“\nFile Attribute: %d”,FileInfo.attributes) ; 


Disk, Directory, and File Management 461 


printé(“\nFile Size: %1d”,FileInfo.file_size) ; 
printf(“\nAllocated Size:%ld”,FileInfo.falloc_size) ; 


DOSCLOSE (Handle) ; 


Example-DosSetFilelinfo 


/* TOUCH.C 

This program demonstrates how to use DosSetFileInfo. 

This program will accept a file name and change the access time 
of the file, allowing the MAKE utility to recognize that the 
file has been changed. 

This program is similar to the TOUCH utility available in UNIX. 
ny 


#Finclude <doscalls.h> 


4#tdefine NORMAL Ox0000 /* normal file attribute */ 
define O_FAIL 0x0000 /* constant for DosOpen */ 
define O_OPEN 0x0001 

ffdefine O_REPLACE 0x0002 

+#define O CREAT 0x0010 /* ereate if file doesn't 


exist */ 


+#define DENY READ 0x0010 /* sharing mode. */ 
+#define DENY WRITE 0x0020 
define DENY NONE 0x0040 


+#define READ ONLY 0x0000 /* access mode */ 
4Kdefine WRITE ONLY 0x0001 
4Kdefine READ WRITE 0x0002 


#fdefine LOBYTE(w) ((char) (w)) 
define HIBYTE(w) (( (unsigned) (w) >> 8) & Oxff) 
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+#define DAY(d) (d & Ox001F) /*date caculation macro*/ 
4tdefine MONTH(d) fd >> 5 & 00007) 

#tdefine YEAR(d) (1980+(d >>9 & Ox007F)) 

+#define HOUR(t) (t >> 11 & OxOOLF)/*time calculation macro*/ 


define MINUTE(t) (t >> 5 & O0x003F) 
Fdefine SEGOND(t) (2 *(t & Ox0D0D0F)) 


struct SetFileStatus | 


unsigned create_date; /* date of file creation */ 
unsigned create_time; j/* time of file creation */ 
unsigned access_date; /* date of last access */ 
unsigned access_time; /* time of last access */ 
unsigned write_date; /* date of last write */ 
unsigned write_time; J» tine of last write */ 


he 


unsigned DateConvert(); 
unsigned TimeConvert(); 


main (argc,argv) 
Int arecs 
char “arev([]: 


{ 


unsigned ret, 
Handle, 
ActionTaken:; 


Btruct FilesStatus Fileinitio: 


struct DateTime datetime; /* parameters for 
DosGetDateTime */ 


char s[80]: 


if jarge > 1) 
strepy(s,arev[1)): 

else { 
printf(“\nPlease enter file name: %s”); 
este le): 
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ret = DOSOPEN( (thar far *)s, 
(unsigned far *)&Handle, 
(unsigned far *)&ActionTaken, 
OL, 


O 9 
O_OPEN, /* o¢2h file at exciets, */ 


J/* elee creates */ 
DENY_NONE | READ_WRITE, 
OL) 3 


if (ret) | 
printf(“\nDosOpen failed %d”,ret); 


DOSEXIT(1,0) 2 


ret = DOSQFILEINFO (Handle, /*ger file inte) 
his i* tile info Level, 


only 1 is available */ 
(ehar far *)SFileinte, 
sigeot(atruct FilesStatus)) = 


if (ret) 
printf (“\nDosQFileInfo failed %d”,ret); 


else { 
/*get current date and 


time* / 
DOSGETDATETIME( (struct DateTime far *)&datetime); 
}*set file info to current 
date and time*/ 
Filelnfo.write_date = DateConvert (&Adatetime) : 
FileInfo.write_time = TimeConvert(&datetime) ; 


ret = DOSSETFILEINFO (Handle, 
iv /* file info level, 


only 1 is available */ 


(ehar far *)&Pileinfo, 
sigeofletruct FilesStatiis)): 


if (ret) 
printf(“\nDid not changed last access date or 


time: %d”,ratr) 2 


else 
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printf(“\n%s was touched. You can now run 
MAKE." 6) 3 
} 
DOSCLOSE (Handle) ; 


unsigned TimeConvert (p) /*convert datetime structtire to */ 
struct DateTime “p; (*a value that SerPileinro* / 
i* Gan tse*/ 


unsigned t = 0; 


t = p-Pseconds / 2: 
t T= p-/ittinutes << 5: 
4 += p-e hour << 113 


fecturn 3 


unsigned DateConvert (p) 
struct DateTime *p; 
{ 


unsiened d = 0; 


d = p--day: 
d= pa emonta << 53 
dest= (p-7year - 1980) << 9: 


return da: 


DosQFileMode and DosSetFileMode 


DosQFileMode determines, and DosSetFileMode sets, the file attribute. Both 
functions expect a file name including drive letter and subdirectory path. 
DosQFileMode requires a pointer to a 2-byte variable where the file attribute will 
be returned. DosSetFileMode expects a pointer to a 2-byte value containing the 
new file attributes for the file. The possible file attributes are described in Chapter 
10. The function DosSetFileMode cannot be used to set the volume label or 
subdirectory bits. 
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DosQFileMode (FileName, CurrentAttribute, Reserved) 


char far *FileName; /* pointer to the filename */ 
unsigned far *CurrentAttribute; /* pointer to the returned attribute */ 
unsigned Reserved; /* must be zero */ 





DosSetFileMode (FileName, CurrentAttribute, Reserved) 


char far *FileName; /* pointer to the filename */ 
unsigned CurrentAttribute; /* pointer to the returned attribute */ 


unsigned Reserved; /* must be zero */ 
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Example 
{/* HIDE.€ 


This program demonstrates how to use DosQFileMode 
SetFileMode. 


The program will accept a file name then hide the 
normal directory listing. 


It’s up to you to write the program to unhide the 
be a good exercise or use any DOS disk utility to 
fila), 


ot | 
include “doscalls.h” 


main (argc,argv) 
Int are; 
char *argv[]: 
{ 
unsigned ret, 
Attribute; 


char s [80]; 
if (arge 7% 1) 


stropy(s,arev (li i: 
else { 


and Dos- 


file from 


rile (it would 
unhide the 


printf(“\nPlease enter file name: %s”); 


gets(s); 


ret = DOSQFILEMODE ((char far *)s, /*get file Mode*/ 


(unsigned far *)&Attribute, 
OL 
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if (ret) 
printf (“*\nDosQFileMode failed %d”,ret);: 
else { 
Attribute |= 0x0002; /*hide the file*/ 
ret = DOSSETFILEMODE ((char far '*)s, 
Attribute, 
Os}; 
if (ret) 
printf(“\nDosSetFileMode failed %d”,ret); 
else 
SLI DET" inte te bidden. 2): 
DosNewSize 


DosNewSize specifies a new size for an opened file. The file handle and the byte 
size of the new file must be specified. The file, however, cannot be a read-only file. 
In order to change the size of a read-only file, DosSetFileMode must first be used 
to change the file attribute to read/write access. The system will attempt to allocate 
or discard the disk space required by the file according to its new size. If the file 
size of an existing file is decreased, the file is truncated and any data located at the 
end of the file, beyond the reduced size, is lost. DosNewSize reallocates disk space 
for an opened file for storing a larger amount of data than is presently needed. The 
new file size should be carefully calculated in order to conserve disk space. 


DosNewSize (FileHandle, FileSize) 


unsigned FileHandle; /* file handle */ 


long FileSize; /* new file size */ 
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DosQVerify and DosSetVerify 


DosQVerify returns the verify option for the current program. DosSetVerify 
sets the verify option. The significance of this option is described in the Chapter 
9. Both functions expect one parameter, VenfySetting, which represents the 
returned verify option or the new verify option, depending on the function. 

The status of the verify setting for a program affects every file opened by the 
program. It cannot be used to set the verify option on an individual file basis. 


DosQVerify (VerifySetting) 


unsigned far *VerifySetting; /* pointer to the returned verify option*/ 





DosSetVerify (VerifySetting) 


unsigned VerifySetting; /* new verify option */ 
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Searching for Files 


OS/2 provides the PATH command which sets up a default directory path. This 
command generates a systemwide variable named DPATH OS/2 (PATH in the 
compatability box), which is also called the environment block. This default 
directory path provides the operating system with a list of directories to search 
when a file is not found in the current directory.’ For example, if the function 
DosOpen calls for a file without a path specification, OS/2 first searches for the file 
in the current default directory, then in all the other directories specified in the 
DPATH variable. 

If the user issues the command, 


PATH=c: \os2:c:\lib:c:\tools:c:\bin 


and the desired file does not reside in the current directory, DosOpen looks in the 
directory c:\os2 for the file, then in directory cNib and so on. The default directory 
string consists of a series of directory names separated by semicolons (;). 

DosSearchPath does almost the same thing as the command PATH. It allows 
each application, when searching for a file, to set up its own default directory path 
instead of using the system default directory path. 

OS/2 also provides a complex set of file searching functions that can search for 
all occurrences (and variations) on a file name on a specified subdirectory. The 
file name specification for these functions can include global characters such as 
wild card (*) or substitution (?), etc. These functions are DosFindFirst, DosFind- 
Next, and DosFindClose. We explain the syntax of these functions later in this 
chapter. If you are not familiar with the global characters, please refer to your OS/ 
2 Users Guide under the section which covers file and directory names. 


DosSearchPath 


DosSearchPath searches for a file in a list of subdirectories and returns the name 
of the subdirectory in which the file was located. Two methods of searching are 
allowed: either the program supplies its own list of subdirectories or the function 
uses a list of subdirectories defined in the environment block (DPATH variable). 
As explained earlier, environment block consists of a series of variables and their 
values. The OS/2 command SET defines a variable and its value, and puts them 
in the environment string. For more information on the environment string, 
please refer to Chapter 2. 


” OS/2 also provides two commands for the program to manipulate the environment block. DosGetEnv gets 
the environment block and DosScanEnv searches through the block for a variable name. For more 
information about environment block and these environment-related functions, please refer to Chapter 2. 
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DosSearchPath expects the following parameters: a control option (Control), 
the path reference (PathRef), the file name (fileName), a pointer to a buffer 
containing the name of the directory in which the file was found ( ResultBuffer), and 
the length of this buffer. 

The Control variable specifies two options: the first is whether the current 
directory is included in the search path. The second is whether an actual search 
string is provided or the value of an environment variable is used. This variable is 
a bit-mask value. 

If bit 0 of Controlis 0, PathRef specifies an actual search path. If not, it specifies 
the name of an environment variable whose value is used for the search path. The 
search path specifies a list of subdirectories to be searched for the file specified by 
FileName. No matter what the source of the list of subdirectories, the list must be 
an ASCIIZ string containing the name of the subdirectories with each name 
separated by a semicolon. 


c:\os2:c:\lib:c:\lotus 


This string indicates the directory c:\os2 will be first searched for the file; then 
cNlib; and lastly, cNotus. 

FileName specifies an ASCIIZ string containing the name of the file to be 
searched. The file name can contain global characters (e.g., a wild card character 
(*)). 

ResultBufferis a pointer to a memory block that returns the name of the file and 
the directory path where the file was found. If the file name string contains a global 
character, the returned result string will also contain the global character. In this 
case, the ResultBuffer should be passed to the function DosFindFirst. If there are 
no global characters in the file name string, the result string will contain the file 
name and the full directory path. In this case the ReswltBuffercan be passed directly 
to function DosOpen to open the file. 

The buffer should contain enough memory to hold the longest possible path 
and filename. The longest possible directory is 64 bytes. ResultBufferLen specifies 
the length of the buffer in number of bytes. Once the directory name is returned, 
the actual length of the string can be determined using C library functions like 
strlen() or by scanning the ASCIIZ string for the location of the null byte. 


DosSearchPath (Control, PathRef, FileName, ResultBuffer, ResultBufferLen) 


unsigned Control; /* specifes the search options */ 


char far *PathRef; /* specifies the search path or 
environment name */ 
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char far *FileName; /* name of file to search for */ 


char far *ResultBuffer; /* buffer where path and file name are 
returned */ 


unsigned ResultBufferLen; /* length of the above buffer */ 
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Example 


/* spath.ec 


This program demonstrates how to use DosSearchPath. 


+/ 
include “doscalls.h” 


Htdefine RESBUFLEN 128 
}t}define ERROR FILE NOT FOUND 2 


#tdefine OPTION_SPATH 0 /* search based on given search 
path */ 

tdefine OPTION CURDIR 1 /* inelude eurrant directory in 
path */ 

define OPTION ENVVAR 2 /* search based on value of an 


environment */ 
/* variable */ 
#tdefine OPTION_ENV_CUR 3 /* inelude current directory in 
variable */ 
main () 
{ 
char ResultBuffer [RESBUFLEN] :; 
unsigned ret; 
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fe serch end eierent. dir *y 
if (ret = DOSSEARCHPATH (OPTION_CURDIR, 
“or\oe2:e:\ie: \bin®,./* esearch path to look frem */ 


"Spat. 2”; /* file neme to search for “/ 
ResultBuffer, 
sizeof (ResultBuffer) )) { 

if (ret == ERROR _FILE_NOT_FOUND) 


prince (*\nFile net found”); 


else 
printf(“\nDosSearchPath failed:%d”,ret) ; 


DOSEXIT (1.0): 


printf(“\nResultBuffer: %s”,ResultBuffer) ; 


/* looking for file based on the value of the environment 
variable *} 

/* you should use DosScanEnv to find out the actual value 
or this. *y 

i* variable *7 

/* search based on environment variable */ 

if (ret = DOSSEARCHPATH (OPTION_ENVVAR, 


"BATH" . | i* gearch path to look from */ 
fepetiye” 5 /* file name to search for */ 
ResultBuffer, 
sizeof (ResultBuffer) )) { 

if (ret == ERROR_FILE_NOT_FOUND) 


Orintr (Wars s- met Found”) ; 


else 
print?’ (“\nDosSearchPath faileds%d”,rer): 


DOSEXIT(1,0) : 
} 
orintt (*\nResultBuffer: %s”,ResultButffer) ; 
DOSE LPL. b 1: 
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DosFindFirst, DosFindNext, and DosFindClose 


DosFindFirst, DosFindNext, and DosFindClose comprise a set of functions 
which search for all occurrences of a file or subdirectory on a specified directory. 
The syntax of these functions is a little bit complex. First, we will learn how to use 
these functions together, and then the syntax of each function will be presented 
separately. 

DosFindFirst finds the first occurence of the file or directory indicated by the 
search name, as well as by the search attribute. DosFindFirst returns a find handle 
which locates the next occurence of the targeted files via DosFindNext. All the 
targeted files can be located, using the find handle and DosFindNext one file ata 
time. Once the program is satisfied that all the files have been found or when a “No 
more files” error is returned, it closes the search by using function DosFindClose. 
Once closed, the find handle is no longer associated with the search name and the 
search attribute. Any further attempt to use DosFindNext with the find handle 
generates an error. For example, these functions, used with the following 
attributes searches the current directory for all its subdirectories. 


filename = **,*” /* looks for all directories in the 
current directory */ 
attribute = DIR /* the search attribute must be set 


to a directory attribute */ 
find handle DosFindFirst (filename, attribute) 
While there are more files to search 
Begin 
DosFindNext (find_handle) 
End 
DosFindClose (find handle) 


DosFindFirst expects several parameters. The file name is specified by an 
ASCIIZ string containing the drive letter, the directory path, and the file name. If 
no drive letter or directory path is mentioned, the current drive or the current 
default directory is assumed. The file name can contain any type of global 
character, including wild cards (*) and substitution characters (?), etc. The 
variable FileName is the pointer to the ASCIIZ string. 

A buffer where the directory or find handle will be returned is also necessary 
(DirHandle). The buffer must contain a value of-1 soa new handle will be allocated 
for DosFindNext. The new find handle value overwrites the original value. If the 
buffer contains a value of 1, no new find handle will be allocated. DosFindNext can 
still use the find handle of value 1 to search for the files. 
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The search attribute indicated by Atinbute specifies the kind of files to be 
searched for. Using this variable, the program can selectively search for system 
files, hidden files, or subdirectories. A value of zero for Attribute searches for 
normal files. Normal file entries include those archived and read/write files. 

DosFindFirst and DosFindNext both expect a pointer to a memory block where 
the information on a file matching the search name and search attribute is 
returned. The returned information is the latest information on each file, up to 
the last time the file information was updated with functions like DosClose or 
DosBufReset. The byte size of this memory block is specified with the variable 
ResultBufLen. For most file searches, the length of the buffer should be 36 bytes. 

The memory block is a data structure with the following format: 


struct FileFindBuf { 
unsigned create_date; /* create date */ 
unsietied create time; /* @reate time */ 
unsigned access_date; /* date of last access */ 
unsiened access time; /* time of last access */ 


ungsisned write date; /* date of last write */ 

unsigned write_time; /* time of lagt write */ 

lone. file size: /* file sige */ 

lene falloc size: /* file allegation size */ 

Wisipned attributes: /* file attribute */ 

ehar string Jen: /* length of file name 
string */ 

ehar file name [13] ;* Fie name. *y 


The significance of each field is discussed on pages 23-24. The file name buffer 
in this structure can be less than 13 bytes, but 13 bytes is recommended. 

OS/2 also keeps track of the number of files or directories that have cumula- 
tively matched the search name and search attribute. This value is returned ina 
buffer specified by the variable SearchCount. 


DosFindFirst (FileName, DirHandle, Attribute, ResultBuf, ResultBufLen, SearchCount, 


Reserved) 
char far *FileName; /* search file name ASCIIZ string */ 
unsigned far *DirHandle; /* pointer to find handle */ 
unsigned Attribute; /* search attribute */ 


struct FileFindBuf far *ResultBuf; /* buffer of returned file info */ 
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unsigned ResultBufLen; /* length of the above buffer */ 


unsigned far *“SearchCount; /* number of matched entries returned */ 


unsigned Reserved; /* must be zero */ 
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DosFindNext (DirHandle, ResultBuf, ResultBufLen, SearchCount) 


unsigned DirHandle; /* pointer to find handle */ 
struct FileFindBuf far *ResultBuf; /* buffer of returned file info. */ 
unsigned ResultBufLen; /* length of the above buffer */ 


unsigned far *SearchCount; /* number of matched entries returned */ 
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DosFindClose (FindHandle) 


unsigned DirHandle; /* pointer to find handle */ 





Example 


/* SEARCH.C 
This program demonstrates how to use DosFindFirst, DosFindNext, 
and DosFindClose, as well as other OS/2 API functions to search 


for the occurence of a string within file(¢). 


This program provide similar functionalities as the GREP program 


under UNIX. 
to use DosFindFirst searching capabilities, 
a commercial product. Therefore HELP features, 


case search, white space etc., 


NOTE: 
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The program is only a demonstration program of how 


and is not meant as 
UPPER and LOWER 


are not included. 


DosFindFirst must be called first which returns a Dirhandle 
which is used to call DosFindNext. 


a 

#tinclude 
include 
#Hinclude 
#tinclude 
include 


+#define 


+#define 
+#define 
define 
define 


define 
+#define 
+#define 


+#define 
define 
+#define 
+#define 
+#define 
+#define 
+#define 


TOLa Hest 


"etdio.o” 
"C68 «ii 


*"doscalle. 
a 


*eubpcalils 
*error. i 


NORMAL 


O_FAIL 
O_OPEN 
O_REPLACE 
O_CREAT 


DENY_READ 
DENY_WRITE 
DENY_NONE 


READ_ONLY 
WRITE _ONLY 
READ_WRITE 
BUFLEN 

CR 

LF 

TAB 


repy(); 


void compare(); 


void dis 
void cls 


play(); 
ee 


nh 


Ox0000 


Ox0000 
OxO0001 
Ox0002 
Ox0010 


Ox0010 
0Ox0020 
Ox0040 


Ox0Q000 
OxO001 
Ox0002 


512 
Ox0OD 


Ox0A 
Ox09 


/* 


/* 


/* 


Moringa! file attkribtite */ 


constant for DosOpen */ 


create if file doesn't exist */ 


sharing mode */ 


Access mode */ 
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/* global variable */ 
int linecount=0; /* jine eount */ 


main(argc,argv) 
Lat argc; 
char *“argy|| : 
{ 
char text[100]:; 


struct FileFindBuf ResBuf; /* search one file at a time */ 
unsigned ResBufLen; 

unsigned SearchCount; 

unsigned DirHandle; 


unsigned fd; /* file handle */ 
unsigned ActionTaken; 
unsigned readsize; 


unsigned Selector; /* parameter for DosAllocSeg */ 


unsigned i; 

lone byteseount,; feize; 

unsigned ret; 

ehar tar bit /* memory buffer */ 


cf (aeee <3). 4 
printt(“\nCommand Format: SEARCH string 
<file name>”); 
printt(*ine.2. SEARCH text *.bat™): 
DOSEXIT (1,0) ; 


ResBufLen = sizeof(struct FileFindBuf) ; 


strepy (text,arev[1]); /* copy search text and ignore */ 

DirHandle = OxFFFF; /* ¢el1i-0S/2 to allocate a new 
handle */ 

SearchCount = 1: 


ret = DOSFINDFIRST((char far *)argv[2], /* file hana */ 
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(unsigned far *)&DirHandle, /* directory handle */ 
0x00, /* sormal atrribute */ 
(struct FileFindBuf far *) &ResBuf, 

ResBufLen, 

(unsigned far *)&SearchCount, 

OL); 


if (SearchCount <—0) { 
printf(“\nNo files of the specification ‘%s’ was 


found”, 
steav (2) ): 
DOSEXIT (1,0): 


Lf (eer): | 
printf (*\nDosFindFirst failed %d",ret) ; 
DOSEXIT(1,0)3 


ret = DOSALLOCSEG (BUFLENt3, 
(unsigned far *)&Selector, 
Os 


if (ee) st 


printf(“\nDosAllocSeg failed %d”,ret); 
DOSEXIT(41 0); 


FP _SEG( but) = Selector: 


FP_OFF (but) = 0; 
/*we have found the file that matches*/ 
/*the file spec. Now we search the*/ 
/*file for the string specified*/ 
elet)3 
while (1) { 
io Open file *7 


Hrafitt (“\nSéarchins throweh Pile: “Fe for “urs’”, 
(char far *)ResButf.file name, 
(char far *) text): 


linecount = 0: 
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ret = DOSOPEN( (char far *)ResBut.file_ name, 
(unsigned far *)&fd, 
(unsigned far *)&ActionTaken, 


Gli, /* N/A WHEN OPEN AN EXISTING FILE */ 
0, j* same as above */ 
O_OPEN, 
DENY_NONE | READ_ONLY, /* open mode */ 
OL) 

4¢ (pet) { 


printt(“\nDosOpen failed: %s 
%d” ,ResBuf.file_name,ret); 
DOSEXIT (1,0); 


fsize — Resbut. tile size: 
bytescount = OL; 
readsize = BUFLEN;: 


while (bytescount < fsize) { 
if (BUFLEN >= (unsigned) (fsize - bytescount) ) 


readsize = (unsigned) (fsize - bytescount) ; 
else 
freadsize = BUFLEN: 
ret = DOSREAD (fd, /* ead tale “7 
(ehar Tar *) bur, 
readsize, 


(unsigned far *)&i); 
*(buftreadsize) =’ \d0': 


if (Peis 4 
printf(“\nError reading file %s error: %d”, 
ResBuf.file_name, ret); 
DOSEXET (1,0): 
} 


bytescountt=readsize; 


compare ((char far *)buf, 
(Char far -*) tert. 
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(char far *)&ResBuf); /* compare buffer */ 
/* with search text */ 


DOSCLOSE (fd) ; 
SearchCount = 1; /*get next file that 


ret =DOSFINDNEXT(DirHandle, matches*/ 
{/*the file epec*/ 
(struct FileFindBuf far *)&ResBuf, 


ResBufLen, 
(unsigned far *)&SearchCount) ; 


if (ret && ret != ERROR_NO_MORE_FILES) { 
printf£(“\nDosFindNext failed: %d”, ret); 
DOSE (1,0) 2 

} 


if (SearchCount <=0) 


} 


break: 


DOSFINDCLOSE (DirHandle) ; 
DOSFREESEG(Selector); 


} 


yoid cls) 


cher e[2] 
e{[@] = *.*: /* eell te replicate: ig a blank */ 
e{1) = 7% /* with normal attributes */ 


/* elear screen */ 
VIOSGROLLUP(G, O, -1. <1, -1, tehear far *)c, 0) 
VIOSETCURPOS(00,0,0);/*move cursor to the top row & col*/ 


void compare (bufl,buf2,resbuf) 
ehat tar *pbuti: 
char far *purZ;: 


484 Advanced Programmer's Guide to OS/2 


struct PileFindBut far *resbut: 
{ 


ehar far “startl: /* search through a buffer */ 

/* for @ sting of text. If 
ehar far *el: /* found, display the line and’ */ 
ehar far *s2: /* the line number */ 


unsigned match; 


stertl = gil = burl: 


e2 = but2: 
fateh = 0% 
while {*sl != *\0")°{ 
17 (*e] == (tebar) LF) 4 
linecountt +; 
start] = ++rei: /* point to the next line */ 
if (toupper(*sl) l= toupper(*s2)) 1 /*tenere cage*/ 
e2 = buf?) 7* af ner mateh */ 
gi: J* get 62 toe, becinning asain */ 
Haten =O: 
} else { 
gitt+; '/* 42 match increase beth pointers */ 
gor 
Lf (lmateh) 
meateh = 1s 
if [%s2 == *\0O") {| #¢* display since the 


sitire */ 
s2 = but2: /* string match */ 
display(startl,linecount) ; 


crstrcepy(target,source) 
char far *target; 
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char far *source: 


{ 


485 


char far “ts /*same as strep y but copies up*/ 
char far *s; {*te-SCR>’ oft <LF?* / 

10 2 

s = source; 


 — Career; 


/* copy string up to NULL or CR or LF */ 


/* and display up to 50 characters of the line 
(char) LF) { 


while (*s != ‘\0’ && *s != (char) CR && *s != 
if (*s == (char) TAB) 
is as 
alk at oat aoe © oe 
if (++i > 50) 
break; 


‘t = *\O*: 


void display(start,count) 
char Tar “start; 
unsigned count; 


{ 
static int line = Zz; 
char text[{60], c: 


/* €opy up to <CR> */ 

erstrepy( (chart fac *) text, chart far “)steart): 
aera Cn Line: 46.6d %“%s",count,text) : 
linet; 

if (line > 23) { 


strepy(text,”Press any key to continue”) ; 


VIOWRTCHARSTR( (char far *) text, 
strlen(text), 

line, 

Oo, OF 

a= "hs 
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while (c == ‘\0’) 
a= getch()s 

linge = 2: 

elet): 


File Control Functions 


In this section we learn how to rename a file, move a file to a new directory, and 
delete a file. DosMove is used to move and/or rename a file. DosDelete removes 
a file from the logical drive. 


DosMove 


DosMove moves a file to a new directory and/or renames it. The file can be 
renamed within the same directory, moved to a new directory with a new name, or 
moved to a new directory with the same name. The old file name and the new 
name, including both old and new subdirectory path, must be specified. The 
directory name cannot include any global characters, such as wild cards (*) or (?). 

DosMove cannot be used to move a file to a different drive. Therefore, the drive 
letter in the old path name and the drive letter of the new path should agree. The 
OS/2 command COPY should be used to copy a file to a different drive. 


DosMove (OldPathName, NewPathName) 


char far *OldPathName; /* ASCIIZ string containing the old 
directory name */ 


char far *NewPathName; /* ASCIIZ string containing the new 
directory name */ 
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DosDelete 


DosDelete removes a file from the logical drive. The full file name is an ASCITZ 
string, and may include the drive letter and the subdirectory path. No global 
characters such as wild cards (*) can be included within the string. The file also 
cannot be aread-only file. ‘To delete a read-only file, the file attribute must first be 
changed to read/write access by using DosSetFileMode. 


DosDelete (FileName, Reserved) 


char far *FileName; /* ASCIIZ string containing the full 
directory name */ 


unsigned Reserved; /* must be zero */ 





Chapter 12 


OS/2 Execution Environment 


nder OS/2, the ability to run several applications at the same time is 

implemented through the concept of the session. The sesszon concept is a 

solution to the problem of sharing a single video adapter (screen), key- 
board, and mouse among the many applications that concurrently execute under 
OS/2. Every application under OS/2 standard edition runs as a seperate session. 
The user can only communicate with one session at a time, though all sessions 
within the system continue to receive CPU cycles (that is, continue to run). The 
session with which user is currently communicating is called the foreground 
session. Only the foreground session can output information to the video screen, 
and accept information from the keyboard and the mouse. All other sessions 
within the system are called background sessions. ‘The user switches from session to 
session, and switches a new session into the foreground with a special operating 
system module called the Sesszon Manager. 

A session, also called a screen group, provides the physical environment for the 
application executing within it. This environment includes logical video, key- 
board, and mouse buffers. Every session or screen group within the system has 
these three logical I/O buffers associated with it. When a session is switched into 
the foreground its logical video, keyboard, and mouse buffers are bound to the 
physical video keyboard and mouse buffers. It can be said that the foreground 
session takes control of the physical keyboard, mouse, and video screen. 

The Session Manager is two things. To the applications it is the watch dog that 
enforces the mutual exclusion to the physical keyboard, mouse, and video screen. 
Only one application at a time has access to them. To the user it is the standard 
user interface for OS/2. When the Presentation Manager becomes available it will 
run as a single session under the Session Manager. 

In this chapter we will address a number of issues. First, we will launch a detailed 
discussion of the session or screen group concept. Then we will present the 
structure, as well as the look and feel of the Session Manager itelf. The last part of 
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the chapter will present a set of API functions which allow applications to control 
and create sessions on their own. 


Background Background 
Session Session 


Logical Logical Logical Logical Logical Logical 
Video Keyboard Mouse Video Keyboard Mouse 
Buffer Buffer(s) Buffer Buffer Buffer(s) Buffer 


Foreground 
Session 


:: ‘Session @:Manager :::: 


. Logical Logical 
ies ae Keyboard Mouse 
utter Buffer(s) Buffer 


g ERLE ies 


Physical Devices 





Figure 12.1 Foreground and Background Sessions 
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Foreground and Background Sessions 


Applications under OS/2 do not interact directly with the user through the 
physical video display, keyboard, and mouse. Rather they perform all such I/O 
through logical buffers maintained by the Session Manager. When a user switches 
a session (and so the application within it) into the foreground, the Session 
Manager associates the logical video, keyboard, and mouse buffers for that session 
with the actual physical buffers for those devices. The application can then receive 
input from the keyboard and mouse, and write to the video screen as if it were the 
only application in the system. 

The relationship of a background session to each of the three logical device 
buffers varies depending on the buffer. Ifa thread within a background session 
attempts to issue a keyboard or mouse function, that thread will be blocked by the 
Session Manager until that session is switched into the foreground. However, any 
application currently running in the background can continue to write to its 
logical video display. This allows background applications to continue updating 
their displays (so when they are switched into the foreground the data that appears 
on the diplays will be current). The only qualification is that this information will 
not appear on the physical video display until the session is switched into the 
foreground. 

A special OS/2 facility discussed in Chapter 16 allows a thread running in a 
background session to “pop-up” and take temporary control of the foreground 
session. This facility is not used to implement TSR’s under OS/2, it is used to allow 
applications running in the background to keep users appraised of important 
developments. An example of a valid use of the pop-up facility is the way in which 
OS/2 uses it for hard error processing. 

The Session Manager in no way interferes with communication among proc- 
esses in different screen groups. A process can continue to communicate with 
processes in any other session or screen group. The Session Manager concept is 
only intended to insure the integrity of the physical keyboard, mouse and video 
display. 


Within Each Session 


Even though the concept of sessions was instituted in order to share the physical 
video display, keyboard, and mouse among multiple applications, italso hasa great 
impact on how applications must behave within each session. This is because, even 
though an application can be made up of multiple processes, the Session Manager 


492 Advanced Programmer's Guide to OS/2 


only provides the synchronization needed to share the physical video display, 
keyboard, and mouse among different screen-groups. Each screen group has a 
single set of logical buffers associated with it, no matter how many processes are 
running within it. This means that if an application wishes to share these buffers 
among various processes it must provide mutual exclusion to make this possible. 
The need to provide mutual exclusion is most crucial for the keyboard and mouse 
buffers. Unrestricted access to the information in these logical buffers by several 
processes would render that information meaningless. OS/2 provides API 
functions (see Chapter 14) that make it easy to implement mutual exclusion on the 
intra-session, interprocess level for the logical keyboard, but not for the mouse. An 
application wishing to share the logical mouse among several processes must 
develop its own mutual exclusion mechanism using the functions discussed in 
Chapter 3. Theoretically itis possible to allow several process within a screen group 
to write to the logical video buffer simultaneously, if they are tightly coupled 
processes—that is, if they cooperate in sending output to the video screen. 

However, we strongly suggest that multi-process applications not be written in 
the form described above, where each process does its own I/O to the logical 
buffers provided for each session. We recommend that applications be written 
such that a single foreground process within each session take care of all the I/O 
operations that involve the logical video, keyboard, and mouse buffers. All other 
processes within that session would then be considered as running in the back- 
ground. Background processes would continue to process, but all the user input 
would be sent to the forground process, and the forground process would be 
responsible for most, if not all of the output to the logical video buffer. 

A detached process is a special sort of background process (its creation is discussed 
in Chapter 2). Unlike anormal child process, a detached process inherits none of 
the resources owned by its parent. It executes asynchronously from its parent 
process, but only in the background. Detached processes are usually used to 
implement device monitors (see Chapter 20). Detached processes within a session 
cannot be terminated by their parent process, nor are they terminated when a 
session is closed bya user. Detached processes must terminate themselves, because 
they run in their own screen group a special session maintained by OS/2. 

When a background process within a screen group needs to communicate with 
the user, the programmer has several alternatives. Ifa background process needs 
only to inform the user of an event, or needs to query the user for a small amount 
of information, then the “pop-up” facility can be used. If the process needs to 
communicate more extensively with the user then perhaps it is wiser to implement 
it as a thread within the foreground process. Alternately, it can use the IPC API 
functions in order to request the foreground process to do user I/O on its behalf. 
The data can then be sent back to the background process using any one of a 
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Keyboard Video Screen 


STDIN 


handle 
Default handles 
received from 
Parent 
Process 


Process 


Alternate file handles, X and Y received from 
Parent process. In this case they are both 
file handles. The fact of this substitution 
does not affect the child process in any way. 





Figure 12.2 Providing I/O for Background Processes by Changing 
STDIN/STDOUT 
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number of data transfer methods. One interesting method for accomplishing this 
is to allow the parent process within a screen group to change the environment 
block for any child processes that need to do I/O to the keyboard, mouse, or video 
screen. In this way STNDIN and STINDOUT for each such process can be specified 
as a pipe or file. The foreground process can read and write to these files whenever 
it needs to provide a background process with user I/O. (see Chapter 10). 


Session Manager Components 


The OS/2 Session Manager is made up of the following components: the 
program selector, the OS/2 base shell, and the screen switcher. ‘The program selector is 
the Session Manager’s interface. It provides a list of currrently running sessions 
and the available applications that can be executed. From the program selector, 
a user can start a new session or select a currently executing session and view its 
output or enter keyboard input. When the user is at the screen of the program 
selector, all other running sessions are in the background and the program 
selector is, itself, the foreground session. 

The OS/2 base shell traps the hot-key sequences used by the Session Manager. 
The key sequence Cntrl-ESC switches the user to the program selector, and Alt-ESC 
switches to the next currently running session in a circular fashion. These key 
sequences are trapped using DosSystemService. 

The screen switcher provides the services necessary to switch different screen 
groups to and from the foreground. The screen switcher responds to service calls 
from the Session Manager whenever session switching is required. For example, 
when a screen group is switched to the background, the screen switcher saves the 
current video memory and hardware status so that they can be restored when the 
session is brought back to the foreground. The Session Manager also provides the 
enforcement that prevents a thread in a background session from issuing a 
keyboard or mouse call. 


Look and Feel of the Session Manager 


When the system first starts, the user 1s presented with the program selector, or 
the menu of the Session Manager. The menu allows the user to choose among 
applications that can be executed by the user and displays the applications that are 
currently executing. The default choices are either a protected mode session or 
a real mode session. OS/2 allows only one real mode session to be running at any 
one time. The user can also add more protected mode applications to the list of 
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executable applications. This is done through the Add menu of the program 
selector. 

Each selection on the program selector represents a session. Every time a new 
protected mode session is picked from the program selector, OS/2 creates a new 
logical keyboard buffer and a logical video buffer, executes the command proces- 
sor cmd.exe, and the command promptis displayed. From the command prompt, 
the user can run any application. The application can start multiple processes and 
each process can start multiple threads. 

Once the application stops running, it returns the user to the command 
prompt. The user can either run another application or issue the OS/2 EXIT 
command to cancel the session and go back to the Session Manager. The session 
is then deleted by OS/2 along with its logical video and keyboard buffers. During 
a session, the user can press Cntrl-ESC to go back to the Session Manager where 
another session can be started or the user can switch te one of the sessions running 
in the background with Alt-ESC. 


Presentation Manager and The Session Manager 


The Session Manager allows multiple applications to co-exist in the system by 
providing each application with its own session. This means that the user can only 
see and communicate with one application ata time. The Presentation Manager, 
on the other hand, allows multiple applications to share the screen, mouse and 
keyboard at once. Interestingly enough, when it is released, the Presentaion 
Manager will not replace the Session Manager. The Presentation Manager will run 
as a session under the Session Manager. The PM will provide the synchronization 
needed to share the resources of a screen group (single logical, video, and 
keyboard buffers) among multiple applications. In addition, the PM will provide 
applications with a graphical interface which is described in the next chapter. 


API for Creating and Managing Sessions 


OS/2 provides the ability for applications to control and create sessions on their 
own, without the need to have the user go through the intermediary step of 
choosing sessions with the Session Manager. This ability can be used to set up 
dedicated systems which restrict the user to a subset of all the system’s resources 
while still taking advantage of OS/2’s multiple session capability. This capability 
is similar to the use of user shells in DOS applications, which shield the user from 
direct access to the operating system (and vise-versa), while still allowing the user 
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access to certain necessary functions. This ability will not often be needed, but in 
situations where a number of applications need to be bundled together to form a 
closed environment for the user, they will be indispensible. 

A session can be created by an OS/2 application using the function DosStartSes- 
sion. Once created, the name of the session is displayed on the selection menu of 
the Session Manager just as if the session was started by the Session Manager. The 
new session can be a child session or an independent session. A child session can 
be terminated by its parent session, or can be otherwise under the parent session's 
control. An independent session can only be stopped by the Session Manager. 
Regardless of the the session’s type, or the way in which it was created, every new 
session is assigned a session ID. With the session ID, an application can control its 
child sessions using API functions. 

A child session can be stopped using DosStopSession. The application can also 
switch a child session into the foreground using DosSelectSession. A session can 
be set so that it is either selectable or non-selectable. A session that is declared as 
selectable can be switched into the foreground, either by its parent session using 
DosSelectSession, or by the user from the Session Manager menu. A session that 
is specified as non-selectable will not appear on the Session Manager menu. This 
is the equivalent of hiding a session from the user and keeping it in the back- 
ground. Iflater on the application wishes to bring this session into the foreground 
it must reset it as selectable. A bond between the parent session and the child 
session can also be established so that whenever the user selects the parent session 
from the Session Manager menu, the child session is loaded into the foreground 
instead of the parent session. To setup the bond option and to specify whether a 
session is selectable or not, the application uses the function DosSetSession. 

OS/2 allows a limit of sixteen (16) protected mode sessions and one real mode 
session. Four protected mode sessions are used by the system, leaving only 12 for 
applications. Since there is but a single real mode session, only one real mode 
application can be run at a time. 


DosStartSession 


DosStartSession creates a new session. The function expects a data structure 
containing seven fields and an address to which it returns the session ID. The 
format of the data structure is as follows: 
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Siruet Brtartintre { 


unsigned Length; /* length of the data 
structure, 22: bytes */ 

unsigned Related; /* eype of session */ 

unsigned FeBg; /* foreground or background 
opticn */ 

char far *PgmTitle; /*-Session title te be appeared 


on the Session Manager’s 
selection menu */ 


char far *PgmName; /* name of program to be 
execute under the session */ 

char tar *Pemlapute: ¢* 42nput fo the sroeeran */ 

char far *TermdQ: /* queue name */ 


ie 


The Length parameter specifies the length of the data structure in number of 
bytes. In this version of OS/2 the length should be 22 bytes with the char far * 
declaration requiring four bytes. 

As explained earlier, a session can be started as an independent session or a 
child session. This option is specified with the parameter Related. If Related equals 
Q, the session is an independent session. Ifit equals 1, the session is a child session. 
The session can be specified to be running in the foreground or background with 
the parameter /gbg. When the session is to run in the foreground, FgBg equals 0. 
Ifitis 1, the process is to run in the background. In order to start a new session in 
the foreground, the calling session or one of its child sessions has to be currently 
running in the foreground. To determine whether a process is in the foreground 
or not, it can use the functions VioScrLock and VioScrUnLock. 

The title of the session, which is displayed as a selection on the Session Manager 
menu, is controlled by the parameter PemTitle. PgmTitle is a FAR pointer to an 
ASCIIZ string containing the title of the session. The string can be no more than 
32 bytes long, not including the null terminator. If the paramter PgmTitle is not 
specified and left as a null pointer, OS/2 makes the program name, represented 
by PgmName, the session title minus its path and drive. 

PgmNameis a FAR pointer to ASCIIZ string. The program name should include 
the drive as well as the path of the program to be executed under the new session. 
PgmInputs is also a FAR pointer to an ASCIIZ string which specifies the arguments 
to be passed to the program. The format of the argument string is: 


Drive: \Path\Pgname 
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The last parameter, TermQ, is an optional parameter which is used by the parent 
session to obtain the return code of a child session when the child session 
completes its execution. TermQcan either be anull string ora pointer to an ASCIIZ 
string containing the name of a queue which was created by the calling process. If 
TermQ specifies the name of a queue, then after the completion of a child session 
the Session Manager writes to the queue a 2-byte data element containing the 
result code of the child session. A parent session obtains this information by having 
a thread read a non-shared memory queue which it has previously set up with 
DosReadQueue (See Chapter 5). The Session Manager does all the transmitting. 

DosReadQueue returns two values: Request Data, and DataAddress. The Request- 
Data parameter is always zero, since the Session Manager does not use it to send 
information. The return code of the child session is found in the parameter 
DataAddress which, however, does not point to a shared memory address. The 
format of this parameter consists of two unsigned or WORD (2-byte) values. The 
first word specifies the child session’s session ID and the second word specifies its 
result code. If the session created with DosStartSession is not a child session, then 
TermQ should be set to Null. If TermQ is set to Null, the Session Manager does not 
send any return codes. 


Struct DataElement { 
unsigned Sesgsion_ID> /* ID of the child session */ 
unsigned Result_Code; /* result code returned by 
the child session */ 


DosStartSession (StartData, Session_!ID) 


struct StartInfo far *StartData; /* start session parameters */ 


unsigned far *Session_ID; /* pointer to session ID to be returned */ 
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DosStopSession 


Using DosStopSession, the parent session can terminate all child sessions 
previously started using DosStartSession, or terminate a single child session. Ifa 
single session is to be terminated, the session ID of the child session has to be 
specified. The session ID is the value returned after the creation of the session by 
DosStartSession. Once a child session is terminated, any sessions created by this 
child session are also terminated. 

DosStopSession can only be used to terminate a child session previously created 
by the parent session. Grandchild sessions, independent sessions, or the calling 
session itself cannot be terminated using this function. Also, DosStopSession must 
be called by the same process that started the session via DosStartSession. Any 
other processes within the calling session cannot use this function to terminate the 
session. 

The parent session can use this function in the foreground or background. If 
the child session is a foreground session, the calling session will be the new 
foreground session in place of the just terminated session. Any bond previously 
established between the parent and child session using DosSetSession will be 
broken. 

When DosStopSession is issued to terminate a child session, OS/2 issues 
DosKillProcess to processes currently running within the session. These processes, 
however, can ignore the terminate signals and continue their execution using 
DosSetSignHandler (See Chapter 3). Ifa process refuses to terminate, OS/2 will 
not generate an error and the session continues its execution. The process that 
issues DosStopSession cannot immediatly know whether the processes running in 
the child session have terminated themselves or ignored the termination request. 
The calling process will have to monitor the return codes on the termination 
queue specified by DosStartSession. When each session terminates, a data element 
consisting of the session ID and the result code is written to the queue by the 
Session Manager. The result code is the data value specified by the child session 
and can be used to pass information to the parent session. 
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DosStopSession (TargetOption, Session_ID) 


unsigned TargetOption; /* session terminating option */ 
unsigned Session_ID; /* session ID */ 
unsigned long Reserve; /* reserve data */ 





DosSelectSession 


DosSelectSession is used to switch a background session into the foreground. 
In order to successfully issue this function either the calling session or one of its 
children must be executing 1n the foreground, otherwise an error will be returned. 
This function has two options. Only a child session or the calling session itself 
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can be switched to the foreground. When a child session is selected, it must have 
been started by the calling session using function DosStartSession. The parent 
session can only select its own child session for foreground execution. No 
grandchild or independent sessions can be the target of this function. Also, 
DosSelectSession must be called by the same process that started the session. No 
other processes within the calling session are permitted to use this function to 
switch a child session. 

When a parent session is in the background and one of its child session is in the 
foreground, this function can be used by the parent session to switch itself into the 
foreground. To do this, the value for the specified Sesszon_ID must be zero. If the 
value of Session_ID is greater than zero, it must correspond to the session ID of the 
selected child session. In order to determine whether a process is in the 
foreground or not, the process can use the function func_name. 


DosSelectSession (Session_ID, Reserved) 


unsigned Session_ID; /* session ID of the targeted child 
session */ 
long Reserved; /* reserved for OS/2 */ 





Session Status 


Using DosSetSession, two categories of child session can be specified: selectable 
or non-selectable, and bound or unbound. 

When a child session is selectable, the Session Manager or the parent session 
using DosSelectSession can switch it to the foreground. If it is non-selectable, the 
child session cannot be switched to the foreground by the parent session or the 
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Session Manager. A non-selectable session does not appear on the program 
selector’s menu. 

A child and a parent session, in the default mode, are not bound together. This 
means that when the child session is selected it is brought into the foreground, and 
when the parent session is selected it is brought into the foreground. 

When parent and child sessions are bound, whenever the parent session is 
selected, the child session is switched to the foreground in its place. When the child 
session is selected, it is brought into the foreground, as usual. 

Itis also possible to bind sessions together in achain. A parent and child session 
can be bound, with the child session, in turn, bound to a grandchild session. If the 
parent session is selected, the grandchild session is brought to the foreground. If 
the child session is brought to the foreground, the grandchild is also brought into 
the foreground. 

A parent session can only be bound to one child session at a time. Whenever 
a new bond is established with another child session, the previous bond is dissolved 
by OS/2. 


If Session 1 is selected by the user then 
Session 3 will become the foreground 
Session session. If Session 2 is chosen by the 
1 user then Session 3 also becomes the 
foreground session. 


Session 1 creates 
child Session 2 using 
the BIND option Session 


2 


Session 2 creates 
child Session 3 using 
the BIND option Session 


3 





Figure 12.3 Binding Sessions 
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DosSetSession 


DosSetSession is used to set the status of a child session. It can only be used by 
a parent session on a child session which it previously created with DosStartSession. 
The parent session can be executing in the foreground or background when it 
issues this function. A grandchild session, an independent session, or the calling 
session itself, cannot be the target of this function. Also, DosSetSession must be 
called by the same process that started the child session. No other processes within 
the calling session can use this function to set the status of the session. 

As disscussed earlier, there are two types of status: selectable or non-selectable, 
and bound or unbound. DosSetSession allows a parent session to set the status of 
one of its child sessions. The function can be used to set either the selectable status 
or the bind status independent of one another. 

Two paramters are required by DosSetSession. One is the session ID of the child 
session, Sesszon_ID. The other is a data structure containing the status information 
of the child session. The data structure is in the following format: 


struct StatusData { 
unsigned Length; /* leneth of the data estructura */ 
unsigned SelectInd;/* selectable option */ 
unsigned BindInd; /* bind option */ 


The Length parameter specifies the length of the data structure in number of 
bytes. With the current version of OS/2, the length is 6 bytes. Select/nd specifies 
whether the child session is selectable, non-selectable, or unchanged. The 
parameter Bindlnd specifies whether the child session will be bound with the 
parent session or not, or whether the current setting will be left unchanged. If the 
unchanged option is used, the current status of the session will remain as it was. 
This allows the parent session to change the bind or select status individually; a 
change in the status of one will not affect the other. 

The possible values of Select/nd are: 
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The possible values for BindInd are: 





DosSetSession (Session_ID, StatusData) 


unsigned Session_ID; /* session ID of the targeted child session */ 


struct StatusData far *Status; /* session status info */ 





Example 
/* SESSION.C 


This program demonstrates how an OS/2 application can: 


start another session using DosStartSession, 
: stop a session via DosStopSession 
° and switch to another session via DosSelectSession. 
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The program will first start a new session with a program 
name, ”CHILD.EXE”. 


| 


include “doscalls.h” 
#include “stdio.h” 


#tdefine CHILDSESSION 1 /* relationship ianfermation */ 
#fdefine INDPSESSION 0 {* for DesStartseseaion */ 
#fdefine FOREGROUND 0 
#fdefine BACKGROUND 1 
#tdefine ALLSESSION i /* Sropsession option */ 
#fdefine SESSION 0 
char PgmTitle[] = “TEST SESSION”; /* gession title */ 
char PgmName[] = 
“o:\\samples\\session\\CHILD.EXE”; /* program name */ 
/* must inelude */ 
/* path and drive */ 
char PgemInputs[] = “areO argl arg2\0”; /* arguments */ 
main () 
{ 
struct StartData Startinfo: /* parameter for 


DosStartSession */ 
unsigned Session_ID; 
unsigned Process_ID; 


char «¢: /* keyboard input 
char */ 


unsigned ret; 
/* assigning information to StartData */ 
Startinto.Lensth = sigsortstruct Startlata) : 


StartInfo.Related = CHILDSESSION; /* child or indpendent 
sess */ 
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StartInfo.FgBg = BACKGROUND; /* fore= or background */ 


Sstartinfo.PemTitie = (char far *)PoemTitle: 
StartInfo.PgmName = (char far *)PgmName; 
Startinfo. Pamilnputs = (char far *)Poemlnputs; 
Startinfo.Term@ = (char far *) NULL: 


printit(“\nStarting a child session: *ks\n”",Startinfo.PemName) : 
ret = DOSSTARTSESSION ( (Struct StartData far *)&8tartinfo, 
(unsigned far *)&Session_ID, 
(unsigned far *)&Process_ID); 
if (ret) { 
pfintr C\n\rDosStartSession failed, %d",ret) : 
DOSEXIT (1,0) 3 
} 


printf(“\nSession started, Session ID: %d Session Title: %s\n”, 
Session_ID, PgmTitle) ; 


printt(*\nYou can press Cntrl-Ese or Alt-Esc to see the other 
session. in”): 
printf(“\nPress N, we will demonstrate how to use 
DosSelecSession.”); 
brintf(“\nPress S&S, to stop the child session and the 
parent session.”); 


while (1) { 
e¢ = getch{): 
if ie == (ohare? |) @ == tebe) “na ) 1 
ret = DOSSELECTSESSION (Session_ID, 
OL) 3 
if (ret) { 


printf ("\nDosSelectSession failed: %d”,ret) ; 
DOUSESIT (1,0) : 

} 

printf (“\nSleeping for 5 seconds”) ; 

ret = DOSSLEEP((long)5000) ; 

printt (“\nswitch back”) + 

ret = DOSSELECTSESSION {(0,0L); 
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if (ec == (char)’S’ || c == (char)’s’) { 
ret = DOSSTOPSESSION (SESSION, 
session ID, 


OL); 
printt("\nSession stopped.”) ; 
if (eer) 4 
printf (“\nDosStopSession failed: 


Yd” ,*eat) : 
DOSEXIT(1,0): 


DOSEXIT(C1.0)+ 


/* GHILD.C */ 


/* This program is a child process started by another process 
from a different session via DosStartSession. 


This program demonstrate how to determine whether a process 
is in the foreground or background using VioScrLock and 
VioScrUnlock. 

i 


winelude “stdio.h” 
include “doscalls.h” 
include “subcalls.h” 


4tdefine EXIT THREAD 0 
4#Hdefine EXIT _ALLTHREAD 1 


main(argc,argv) 
Lat areac; 
char *arev([]: 
{ 
int actioncode; 
int resultcode; 
int a, flag; (* flase */ 


508 Advanced Programmer's Guide to OS/2 


char status; /* use for VioSerLock */ 
erince "= \oTEST SESSION 7)‘: 


it laree » 1) 

erintt (*\nAroument 0: “es” ,arev[0)]); 
it larec > 2) 

printf(“\nArgument 1: %s”,argvll1]); 
Lf (arae 2 3) 

printf(“\nArgument 2: %s”,argvl2]); 


orintt ("\nSleep until stepped by parent session”); 
a Moa 
Flas = 0; 


while (1) { 
/* determine whether the process is in the background */ 


VIOSCRLOCK(0, (char far *)&status,0O): i* gok wait */ 
if (status ==0) { /* successful lock */ 
VIOSCRUNLOCK (0); 
if (flag) 


printi(*\nTEST SESSION is eurrently in 
foreground %d time(s)”,it+) ; 
flags =0; 
} else 
fiag = 1} 


} 

actioncode => EXIT ALLTHREAD; 

resultcode 20% /* completion code to 
be passed to the*/ 


DOSEXIT(actioncode, resultcode) ; 


Chapter 13 


Video Functions 


resentation plays avery important role in the success of an application. Users 

tend to base their judgment of an application just as much on the quality of 

the user interface as on its capabilities. The form of presentation and its 
speed are the most important elements in a user interface. A program that 
presents its information to the user in a slow, awkward manner is perceived as 
unsophisticated, even if it employs a fast and powerful algorithm. 

Because of this, programmers should use the fastest possible method of 
outputting information to the video adapter. Speed becomes a real issue for 
programs using a complex display (graphics-intensive programs, sophisticated 
word processors, and desktop publishing programs). The video functions 
provided by DOS are rather slow and limited. The need for fast presentation of 
data forces DOS programmers to go around the operating system to the faster 
BIOS video functions or even to directly manipulate the memory and registers of 
the video adapter itself". 

By contrast, the video services provided by OS/2 are fast, efficient, straight- 
forward, and well documented. Programmers no longer need to resort to the 
hardware technical references or arcana gleaned from computer magazines and 
bulletin board systems to experiment with the low level BIOS interrupts. Even 
when an application requires greater graphics capabilities, it can directly manipu- 
late the registers, as well as the video memory buffer, of the video adapter. This type 
of video manipulation is not recommended, however, because it causes compati- 
bility problems with the Presentation Manager (a graphics-based operating system 
which will soon be made available by IBM and Microsoft) and future versions of 
OS/2. 


‘For DOS applications, there are three methods of video display manipulation: using DOS interrupt 21H, using 
BIOS interrupt 10H, or directly manipulating the video memory buffers and registers of the graphic adapter. 
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In this chapter we learn the basic structure of the video subsystem and the basic 
video functions (including those that configure the video adapter and monitor). 
We also present a discussion of the issues that developers face when developing 
_ applications to be compatible with the Presentation Manager. 


Background and Foreground Screen Groups 


As discussed in Chapter 2, each OS/2 application operates within its own screen 
group, or session. Each screen group has control over its own logical video buffer 
which manipulates the video display as if it were the only application using the 
display monitor. The implementation of a separate logical display buffer for each 
application prevents synchronization problems resulting from multiple applica- 
tions writing to the same video display buffer. 

Using OS/2’s video API functions, OS/2 applications manipulate their own 
logical display buffer without concerning themselves with other applications. 
Once a session is selected by the user, OS/2 sends its logical display buffer to the 
physical display adapter. The selected session is called the foreground screen group, 
and all other sessions are background screen groups. 

A foreground screen group is simply the most recently selected session. Any 
changes in the logical video buffer of the foreground session are automatically sent 
to the physical display. This makes it seem like the foreground session is 
controlling the display of the video monitor. Any changes in the background 
screen group’s logical video buffer are not displayed on the video monitor until 
that session is selected to be the foreground screen group. OS/2, however, allows 
a background session to assume temporary control of the video monitor using the 
function VioPopUp which is discussed in Chapter 16. 


0OS/2 Video Subsystem 


The part of OS/2 which provides the video services is usually referred to as the 
video subsystem. This subsystem consists of a complex set of video functions. Each 
video function is distinguished by having the three-character “VIO” in front of its 
name. These VIO functions are implemented using a dynamic-link library 
(VioCalls.Dll) which means that the code for the VIO functions is loaded into 
memory when they are called rather than at program load time. Dynamic linking 
is explained in Chapter 9. Implementing the video subsystem as a dynamic link 
library allows it to be changed depending on the type of video adapter being used 
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without the problems involved in changing operating system code or the function 
calls within applications. In fact, by substituting the dynamic link library 
VioCalls.DLL with others, different sets of video services can be substituted to 
support other types of video adapters. This feature of OS/2’s design makes it 
simple for the operating system to be extended to accomodate new hardware 
devices. OS/2’s built-in extendability marks a tremendous improvement over 
DOS, where support for a new device often meant rewriting the BIOS. 

The video API functions are separated into the following categories: 


= Video system configuration and display set-up functions specify and set up 


the type of video adapter board and video monitor connected to the 
system, the mode of the adapter, and the state of the monitor. 


Cursor control functions allow the application to determine and set the 
position of the cursor. 


Screen control functions. Using all or part of these functions, the applica- 
tion can scroll left, right, up or down, and clear the screen. 


# ASCII character display functions provide facilities to display ASCII char- 


acters on the video screen or to determine which characters are on the 
screen. 


#" ANSI support functions. The two ANSI video functions allow the video 


adapter to set the video subsystem to accept ANSI screen control and text 
display escape sequences. 


National support functions allow code-page switching in order to switch to 
the character sets used by different languages. 


Font control functions. Allow applications to change or add text fonts to 
the video adapter. These fonts are not graphical screen fonts used for 
desktop publishing, but rather simple text fonts used to display ASCII 
characters. Font control functions are not compatible with the Presenta- 
tion Manager and are discussed in Chapter 16. 


Logical and Physical Video Buffer Manipulations. These functions ma- 
nipulate the logical video buffer or the actual physical video buffer located 
on the video adapter itself. These functions are not compatible with the 
Presentation Manager and are discussed in Chapter 16. 


Pop-Up functions allow a background process to temporarily pop-up from 
the background to the foreground session to notify the user of important 
events. These functions are not compatible with the Presentation Manager 
and are discussed in Chapter 16. 


512 Advanced Programmer's Guide to OS/2 


™ Video Subsystem functions. OS/2 allows an application to substitute its 
own VIO functions for the predefined routines provided by OS/2, making 
it possible to install a video subsystem that is entirely different from OS/2’s. 
These functions are not compatible with the OS/2 Presentation Manager 
and are discussed in Chapter 17. 


The OS/2 video functions that deal with the video adapter mode and state, 
screen control, font control, cursor control, and display of ASCII characters, are 
analagous to those services provided by the ROM BIOS interrupt 10H and DOS 
Interrupt 21H. The functions used to manipulate the physical or logical buffer are 
similiar to the direct memory access techniques used by DOS applications to 
manipulate the video memory of the graphic adapter. The pop-up and video 
subsystem functions are new categories of functions introduced by OS/2. 

The OS/2 video subsystem is designed to support text-based applications. It 
provides none of the sophisticated graphics functions required for the develop- 
ment of graphics-based applications, such as screen fonts, graphical drawing or 
painting, support for laser printers, etc. The Presentation Manager will provide 
these types of functions. 


Presentation Manager Application 
and OS/2 Application 


OS/2 application developers should make their applications compatible with 
the soon-to-be-released MS and IBM OS/2 Presentation Manager (PM). After 
some initial uncertainty about IBM and Microsofts’s PM design philosophies it 
turns out that they will be the same animal after all. The new PM will have a 
standard graphical application and user interface. As far as the end user is 
concerned, the PM will have the look and feel of the Microsoft Windows environ- 
ment, but with extended capabilities. Developers schooled in the Windows 
tradition should have no trouble adjusting to the use of the functions provided by 
the PM. However, the PM is based on an entirely different concept: the Graphical 
Display Data Manager (GDDM), a mainframe graphical application interface. 
GDDM is consistent with IBM’s System Application Architecture (SAA), a standard 
application development architecture proposed by IBM for mainframe, mini- and 
microcomputers. The decision to go with a SAA based Presentation Manager for 
OS/2 should be welcomed by developers and users concerned with portability and 
connectivity. 
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The Presentation Manager will work by providing additional API functions, 
whole new categories of functions, and functions that supercede the ones provided 
by standard OS/2 VIO API. (The PM will replace OS/2’s standard API functions 
with functions from its own dynamic link libraries whenever necessary.) Using 
these functions applications will take advantage of such features as screen text 
fonts, windows, dialog boxes, pull-down menus, and advanced graphics drawing 
and painting capabilities. Applications that use the OS/2 API for text-based 
applications will be able to run as windows within the PM. This means that the 
progress of several applications can be simultaneously followed, with each occupy- 
ing a different portion of the screen. Applications which directly manipulate the 
logical video buffer or the video adapter will not be able to run as a window within 
the PM’s multi-window environment. These applications, however, will be able to 
run as separate screens under the PM. 

There is a growing consensus in the industry about the need for a consistent user 
and application interface. A user interface is the set of procedures that govern the 
“conversation” the user has with an application. A consistent user interface across 
applications aids users when learning new applications. Since the average 
computer user needs to be fluent in several applications the need for easy learning 
is growing. Indeed, the advent of true multitasking makes the need for a consistent 
user interface even more acute. Under the PM’s multi-window environment, the 
user will typically interact with several applications at once. Constantly switching 
user interfaces will diminish the potential for increased productivity inherent in 
the PM concept. From the developer’s point of view, writing applications for the 
PM will require a great deal of start-up preparation to learn the PM execution 
environment, and also a great deal of programming overhead when writing 
applications (to write code that adheres to the PM’s conventions). In exchange of 
these constraints, the programmer receives a sophisticated set of graphical appli- 
cation development tools that are device independent and the assurance that the 
applications will take advantage of what will be, in all probability, the standard 
execution environment for microcomputer based applications. The only alterna- 
tive for the developer is to use a third party graphical program interface or to 
develop anew one. In both of these cases, however, the resultant application will 
not run as a window under the Presentation Manager. When implementing a new 
graphical program interface, the application itself must support the endless variety 
of video adapters and laser printers on the market. Under the PM, the device 
manufacturers will provide all the necessary interfaces. 
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Text-Based Applications, Dialog Manager, and 
Presentation Manager 


IBM’s System Application Architecture (SAA) provides a detailed definition of 
two interfaces. The Presentation Manager will be the standard user interface and 
application interface for graphics based applications. The Dialog Manager is the 
proposed standard user and application interface for text-based applications. The 
user interface for the SAA Dialog Manager consists of simple pop-up and bounced- 
bar menus and is easily implemented using OS/2 video functions. The Session 
Manager provided with the current version of OS/2 is an example of a Dialog 
Manager type user interface. 

The necessity for developers to implement a standard user interface is appli- 
cable to the developers of text-based applications as well. We recommend that 
programmers use the interface conventions of the SAA Dialog Manager, instead 
of developing one of their own. Examples of programs using a Dialog Manager 
type user interface are IBM’s Display Write 4 and IBM OS/2 FE. Alternately, text- 
based applications can use the standard VIO functions to mimic the Presentation 
Manager. To be compatible with the PM, screen fonts, multiple windows, or the 
direct manipulation of the video adapter should not be mimicked. When the PM 
finally becomes available these applications can be modified to take advantage of 
special PM capabilities. Microsoft’s CodeView is a good example of a text-based 
application which has a user interface modeled after the Presentation Manager's. 


Video System Configuration and Display Set-up 


To produce the best possible display, an application needs to set up its video 
display for the type of the adapter and the monitor installed in the system. Because 
of the great variety of video adapters and monitors available, there are many 
possible display modes and states. Under DOS, the programmer either has to use 
the modes or display states predefined by the BIOS or change them by sending 
special codes with low level calls to the BIOS itself. ‘This is an awkward approach. 
OS/2 makes configuring the graphics adapter and display simpler by specifying 
parameters to a set of API functions. 

OS/2 provides functions to determine the current display configuration of the 
system, set the mode of the video adapter, and set the state of the video adapter in 
each of its possible modes. VioGetConfig returns the display configuration of the 
system, including the type of adapter and monitor. Certain video adapters support 
various video modes (text or graphics, various degrees of resolution, different 
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numbers of rows and columns, etc.) VioGetMode and VioSetMode determine and 
set the mode of the video adapter depending on the type of display installed. The 
video adapter can be in configured in a different state for each mode (1.e., type of 
overscan color, blinking or high intensity background, etc.) VioGetState and 
VioSetState are used to determine and set the state of the video adapter in each 
mode: For example, under OS/2 an application can set the display mode to 80 x 
43 text mode with 16 colors, and color burst using VioSetMode. Under DOS, the 
application must use several calls to the BIOS interrupt 10H with predefined codes 
to do the same thing. 

This section explains the syntax of the API functions dealing with the configu- 
ration of the video display and offers advice on how to use them. We do not discuss 
the direct manipulation of any type of video adapter (1.e., direct video memory 
access or controlling the registers of the video adapter). 


VioGetConfig 


A video display system consists of one or two video adapters and a monitor. 
There are many types of video adapters and monitors on the market, but OS/2 only 
recognizes the standard equipment supported by IBM. OS/2 supports the 
following adapters: monochrome graphics adapters (MGA), color graphics adapt- 
ers (CGA), enhanced graphics adapters (EGA), and virtual graphics array adapters 
(VGA). OS/2 recognizes the following types of monitors: monochrome, color, 
enhanced color, and virtual graphics array monitors. For each type of adapter, 
OS/2 can determine how much memory is installed. Even though the memory 
installed on the MGA, CGA and VGA is well documented, an application should 
determine it using the function VioGetConfig. This will help applications remain 
compatible with future generations of video adapters. 

To determine which type of video adapter or monitor is installed in the system, 
OS/2 performs various tests (i.e., setting different switches on the mother board 
or adapter cards). If the graphics board installed in the system emulates any of the 
supported equipment, it should work with OS/2. For other types of adapters or 
monitors, the manufacturer of the equipment must provide the necessary device 
drivers to use the equipment with OS/2. In Chapter 17, we show how an 
application can substitute its own video subsystem for the default OS/2 video 
subsystem. OS/2 cannot detect whether the monitor is connected to the video 
adapter. Nor can it detect if the switch settings on the video adapter are incorrect. 
In this latter case, OS/2 inadvertantly returns the incorrect monitor type. 

VioGetConfig expects a pointer to a data structure where the configuration 
information is returned. The format of the data structure should be as follows: 
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struct Vio Ganfig | 


unsigned length; © {* Length of the data 
structure */ 
unsigned adapter_type:; /* wideo adapter type */ 
unsigned display_type; /* display moniter 
type */ 
unsigned long memory_size; /* memory installed on 


adapter */ 
} 


The field length specifies the length of the data structure including the field 
length itself in number of bytes. It should not be larger than 10. The length of the 
data structure is specified for the future, when the information of the video 
configuration might require more than three parameters. The field length should 
not be set to a predefined value, but should represent the length of the data 
structure during the time of execution. For C programs, the program should use 
the sizeof() function to determine its size. 


length = sigeof (struet Vio_Config) : 


The parameter adapter_type specifies the type of video adapter installed on the 
system. The returned value of this parameter is determined by the following: 





The parameter display_type specifies the type of video display connected to the 
system. The value and meaning of the parameter is as follows: 


Video Functions 517 





The parameter memory specifies the amount of memory installed on the 
adapter in number of bytes. The value is returned as a 32-bit value or as a long 
variable. 


VioGetConfig(Reserved, ConfigData, VioHandle) 


unsigned Reserved; /* Reserved field must equal zero (0)*/ 


struct Vio_Config far * ConfigData; /* Pointer to configuration data 
structure */ 


unsigned VioHandle; /* Video handle (reserved) must be zero 


(O) */ 
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Example 
/* VIOCONFIG.C 


This program demonstrates how to use VioGetConfig 
*/ 


include “doscalls.h” 
include “subcalls.h” 


#define MONO 0 /* graphics adapter type */ 

#tdefine CGA 1 J/* and moniter type */ 

define EGA 2 

#tdefine VGA 5 

define M8503 3 /* 8503 Monochrome display */ 

itdefine DVGA 4 /* IBM VGA 8512, 8513 or 8514 display */ 
main () 


{ 
struct ConfigData VioConfig; 
unsigned ret; 


VioConfig.length = sizeof (struct ConfigData) ; 


ret = VIOGETCONFIG (0, 
/* reserved */ 
(struct ConfigData far *)&VioConfig,0); 
/* video handle */ 


Lf (eet) { 
printf(“\nVioGetConfig failed %d”,ret); 
DOSEXIT(1,0) ; 


printf(“\nGraphic Adapter Type: “); 
switch (VioConfig.adapter_type) [{ 
case MONO: 
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printf(“Monographic Adapter”); 
break; 

case CGA: 
printf(“Color Graphics (CGA)”); 
break; 

case EGA: 
printf(“Enhanced Graphics (EGA)”) ; 
break; 

case VGA: 
printf(“Video Graphics Array (VGA)”); 
break; 

default: 
printf (“Other”) ; 

} 


printf (“\nMonitor Type: “); 
switch (VioConfig.display_type) { 
case MONO: 
printt (“Monographie Monitor”); 
break; 
case CGA: 
printf(“Color Graphics Monitor (CGA)”); 
break; 
case EGA: 
printf (“Enhanced Graphics Monitor (EGA)”) ; 
break; 
case M8503: 
printf(“IBM 8503 Monochrome display”); 
break; 
case DVGA: 
printf(“Video Graphics Array (VGA)”); 
break; 
default: 
printed? | “Orcher*) > 
} 


printf(“\nAmount of Video RAM on board:%1dK”, 
(VioConfig.memory_size/1024)); 
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VioGetMode and VioSetMode 


The mode of a video adapter represents its current setting and governs the 
number of colors, the number of rows and columns, the horizontal and vertical 
resolution, and the display mode of the adapter (text or graphics). 

Each type of video adapter has its own set of possible modes. The MGA has only 
two modes: text and graphics; the CGA has nine modes. The EGA supports all the 
display modes of the MGA and CGA plus four of its own. ‘The VGA supports all the 
modes of the EGA and three more display modes. As Tables 13.1-13.4 show, each 
display mode represents a different number of colors, display resolution, and 
cursor resolution. 

The type of display mode one can choose is limited to those supported by the 
system’s video adapter and monitor. For example, if the adapter is a CGA, it is not 
possible to set the resolution to the MGA’s 720 x 350 or the EGA’s 640 x 350. Only 
if the adapter and the monitor are of the EGA or VGA type, can the number of rows 
be set to either 25, 33, or 43 lines. 

Future display adapters and monitors will allow for more flexibility in configur- 
ing the display mode. Applications will probably not be limited to certain 
combinations of settings for horizontal and vertical resolution or the number of 
rows and columns, but will be able to specify the combination of attributes that best 
suit their purposes. For this reason, OS/2 does not simply set the display mode 
from the BIOS mode number, which refers to a set of prespecified display 
attributes, but demands that each video display parameter be set separately. This 
may seem like extra work for now, but it takes into account future types of display 
adapters and monitors, without forcing the programmer to cope with a constantly 
expanding list of BIOS mode numbers. 


Mode# Type Buffer Colors Alpha Box Resolution 
Address Format Size 
ri Text B0000 4 80x25 9x14 720x350 
F Graphics AQ0O0O 4 80x25 = &x 14 640x350 


(The mode # represents the mode number specified by the BIOS.) 


Table 13.1 MGA Display Modes 
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Mode # Type Buffer Colors Alpha Box Resolution 
Address Format Size 
0 Text B8000 2 40x25 8x8 320x200 
] Text B8000 40x25 8x8 320x200 
2 Text B8000 2 80x25 8x8 640x200 
3 Text B8000 4: 80x25 8x8 640x200 
4 Graphic B8000 4 40x25 8x8 320x200 
5 Graphic B8000 4 40x25 8x8 320x200 
6 Graphic B8000 2 80x25 8x8 640x200 
Table 13.2 CGA Display Modes 
Mode # Type Buffer Colors Alpha Box Resolution 
Address Format Size 
0 Text B8000 16/64 40x25 8x8 320x200 
1 Text B8000 =16/64 40x25 8x8 320x200 
2 Text B8000 3816/64 80x25 8x8 640x200 
3 Text B8000 16/64 80x25 8x8 640x200 
4 Graphic B8000 4 40x25 8x8 320x200 
5 Graphic B8000 4 40x25 8x8 320x200 
6 Graphic B8000 z 80x25 8x8 640x200 
7 Text B0000 4 80x25 9x14 720x350 
D Graphic B8000 16 40x25 8x8 320x200 
E Graphic B8000 16 80x25 8x8 640x200 
F Graphic AQ000 4 80x25 8x14 640x350 
10 Graphic AQ000 4/16 80x25 8x14 640x350 
16/64 


Table 13.3 EGA Display Modes 


Table 13.3 describes the available EGA modes when an EGA monitor is 
attached. Ifa CGA monitor is attached, only modes 0 - 6, D, and E are available 
(with color restrictions appropriate to the capabilities of the monitor). EGA only 
supports modes 7 and F when connected to a monochrome monitor. The values 
in the Color column reflect either 16 colors chosen from a 64-color palette or 4 
colors from a 16-color palette. For mode 10, there are two available color 
configurations depending on whether more than 64K of memory is installed. If 
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128K or 256K of memory is installed on the EGA, the color configuration is 16/64, 
otherwise it is 4/16. The Box Size column specifies the dimensions of each 
character (in terms of number of pixels) as generated by the adapter. A box size 
of 9 x 14 means that each character requires 9 rows and 14 columns of pixels. 


Mode # Type Buffer Colors Alpha Box Resolution 
Address Format Size 
0 Text B8000 64 40x25 8x8 320x200 
] Text B8000 64 40x25 8x14 320x350 
2 Text B8000 64 80x25 8x8 640x200 
3 Text B8000 64 80x25 8x14 640x350 
4 Graphic B8000 4 40x25 8x8 320x200 
D Graphic B8000 4 40x25 8x8 320x200 
6 Graphic B8000 2 80x25 8x8 640x200 
7 Text BO0000 4 80x25 9x16 720x400 
D Graphic B8000 16 40x25 8x8 320x200 
E Graphic B8000 16 80x25 8x8 640x200 
F Graphic A0000 4 80x25 8x14 640x350 
10 Graphic A0000 64 80x25 8x14 640x350 
il Graphic A0000 Z 80x30 8x16 640x480 
12 Graphic A0Q000 16 80x30 8x16 640x480 
13 Graphic A0000 256 40x25 8x8 320x200 


Table 13.4 VGA Display Modes 


The syntax for VioGetMode and VioSetMode is the same. VioGetMode expects 
a pointer to a data structure where the display mode information is returned. 
VioSetMode expects the same data structure, but the information in it is used to 
change the display mode of the video adapter. The format of the data structure 
is as follows: 


struct Vio Mode { 


unsigned Length; /* Jeneth of the data 
structure */ 

char Type; /* display mode*/ 

char Color: /* sumber of colors */ 


unsigned Columns; /* number of columns */ 
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unsigned Rows; /* number of rows */ 
unsigned HorizRes; /* number of pels per column */ 
unsigned VertRes; /** oumber of pale per row */ 


The field length specifies the length of the data structure including the field 
length itself in number of bytes. It should not be larger than 12. The length field 
is intended for the future when more than 12 bytes of memory might be needed 
to set the display mode. We recommend that the field length should not be set to 
a pre-defined value, but represent the length of the data structure during the time 
of execution. For C programs, the program should use the sizeof() function, 


length = sizeof (struct Vio_Mode) ; 


The parameter type specifies the display mode of the video adapter. It is a bit- 
mask value. ‘This means that the meaning of each bit is independent of the others. 
OS/2 determines the display mode by reading off the state of each bit. Bit 0 
determines whether another type of adapter is installed instead of the MGA. Bit 
1 indicates either text or graphic mode. If graphic mode is specified, alphanu- 
meric characters cannot be output to the display. Bit 2 represents whether color 
burst is on or off. The following explains the meaning of each bit in the type 
parameter: 





The parameter Color indicates the number of possible colors the monitor can 
produce. This parameter is equivalent to the color bits specified with the BIOS 
interrrupt 1OH. The possible values for this parameter are: 
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The parameters columns and rows specify the number of alphanumeric columns 
and rows to which the monitor is currently set. The CGA supports either 40 or 80 
columns. The EGA and VGA support 40, or 80. The MGA only supports 80 column 
mode. The EGA and VGA adapters support 25 and 43 rows for text display*. The 
CGA supports 16 and 25 rows. ‘The MGA, however, only supports 25 rows. Please 
note that current video adapters only support certain combinations of row and 
column settings, 25 x 80, 25 x 40, 33 x 80, or 43 x 80 (there might be a 132-column 
mode). Therefore, the row and column specified by the application should 
correspond with the configuration supported by the specific adapter. If the 40- 
column mode is specified, the number of rows must be 16. 

Parameters horizRres and vertRez indicate the number of pixels or pels (picture 
elements) to which the video adapter is currently set or will be set. Once again the 
adapter can only support certain types of horizontal and vertical resolution: 320 x 
200, 640 x 200 for CGA, EGA, and VGA; 720 x 350 for MGA, EGA, and VGA; 640 
x 350 for EGA and VGA; or 720 x 400, 640 x 480 for VGA only. An application 
should not specify a configuration that is not supported by the video adapter it is 
using. For example, if the horizontal resolution is set to 750, the vertical resolution 
should be set to 350 for the MGA and EGA connected to a monochrome monitor 
or for a VGA connected to a VGA monitor. 

For a monochrome adapter and a monochrome monitor, the data structure 
should look like this: | 


Parameter Value 
Type 00000000 
Color 0 
Columns 80 

Rows 25 


Function VioSetMode and VioGetMode does not support 33 row modes. 
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HorizRez 720 
VertRez 350 


For a CGA adapter in graphics mode with a 320 x 200 resolution and a 25 x 40 
text display format, four colors and color burst on, the data structure should be: 


Parameter Value 
Type 00000010 
Color 2 
Columns 40 

Rows 25 
HorizRez 320 
VertRez 200 


The values for every possible combination of video adapter and video monitor 
are too numerous to list here. The programmer should experiment with different 
combinations for each video adapter to determine the best possible configuration 
for his or her application. 

Unlike the familiar BIOS Int 10H set mode function, the API function Vio- 
SetMode does not clear the screen. To clear the screen, use function VioScrollUp. 


VioGetMode(ModeData, VioHandle) 


VioSetMode(ModeData, VioHandle) 


struct Vio_ Mode far *ModeData; /* data structure of mode information */ 


unsigned VioHandle; /* reserved, must be set to 0 */ 
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Example 


/* VIOMODE.C 


uF: 


include “doscalls.h” 
include “subcalls.h” 


/* screen modes */ 


#fdefine MONO 0 
ftdefine NON_MONO 1 /* text mode */ 
#tdefine GRAPHICS 2 /* graphics mode */ 
dtdefine COLORBURST 4 /* colorburst enabled */ 
#fdefine ERROR_VIO_MODE 
$55 /* unsupported screen mode */ 


main() 


struct ModeData VioMode; 
unsigned ret, numcolor; 


char def; /* default screen mode */ 
VioMode.length = sizeof (struct ModeData) ; 


if (ret = VIOGETMODE(&VioMode, 0O)) { 
printf(“\nVioGetMode failed: %d”, ret); 
DOSEXIT(1,0); 


def = VioMode.type; 
printf(“\nCurrent Screen Mode: %d”, 
(unsigned) VioMode.type) ; 


/* get number of colors */ 
printf(“\nNumber of Colors: %d”, (unsigned) (VioMode.color 
S< 23) 
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printf(“\nText Screen Resolution: %d x %d”, 
VioMode.row, VioMode.col); 
printf(“\nGraphics Resolution: %d x %d pixels”, 
VioMode.hres,VioMode.vres) ; 
printf(“\nFormat ID: %d”, (unsigned) VioMode.fmt_ID) ; 
printf(“\nAttribute Count: %d”, (unsigned) VioMode.attrib) ; 


printf(“\n\nSwitching to Graphics Mode”); 

printf(“\nYou will see garbage on the screen.”); 
printf(“\nThis is what text look like in graphics mode”); 
DOSSLEEP ( (long) 2000) ; 


VioMode.type =(char) GRAPHICS | NON_MONO; 


if (ret = VIOSETMODE(&VioMode, 0)) { 
printf(“\nVioSetMode failed %d”,ret); 
DOSEXIT (1,0); 

DOSSLEEP ( (long) 3000) ; 


VioMode.type = def; 

if (ret = VIOSETMODE(&VioMode, 0O)) { 
printf(“\nVioSetMode failed %d”,ret); 
DOSEXIT(1,O); 

printf(“\nSwitching back to text mode”); 


DOSEXIT(1,0); 


The Color Palette 


The attributes of each pixel for the CGA are controlled by one bit in high 
resolution mode and two bits in medium resolution mode. Even though the CGA 
can support 16 colors, the limited amount of video memory on the board enables 
only four colors to be displayed for each pixel in medium resolution and two colors 
in high resolution. For high resolution, the two colors are black or white. But for 
medium resolution, the application has two palettes from which to set three of the 
colors. ‘The fourth color is one of 16 possible colors and is determined by changing 
the attribute bits of the display. The colors in the two palettes are green/red/ 
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brown or cyan/magenta/white. A CGA application cannot choose the colors 
available in the palette, but can pick which palette to use for the pixel color. 

An EGA installed with 128K or 256K of memory and an enhanced color 
monitor, has a palette of 16 out of 64 possible colors. First, the application must 
specify which 16 colors will make up the pallette. VioSetState allows this to be done 
easily. Once the palette has been set up an application specifies four attribute bits 
(16 possible values) to specify the color of each pixel that appears on the screen. 
The four attribute bits choose a color from the palette. For the EGA, the 
appearance of the pixels on the screen are the result of the attribute bits loading 
a new value from the palette array into the palette register of the video adapter. 

The color values that make up the palette are stored in a 16-elementarray. They 
are set using the VioSetState. Each slot represents one color value on the pallette. 
Each element on the array is one byte long. Applications specify which color 
appears on the screen with a four-bit attribute value. This four-bit value chooses 
a color by specifying a position on the 16-element palette array. For example, a 
color attribute value of three, corresponds to the palette register bits stored in the 
third element of the 16-element array. 

Each slot on the palette array determines which color will be displayed on the 
screen. The color is determined by the values of bits 0 - 5 of each slot (bits 6 and 
7 are insignificant). These six bits are similiar to the IRGB® value for a character 
attribute. For an enhanced display, bits 0-2 represent the Red (R), Green (G), and 
Blue (B) signals which produce dark colors. The bits 4 - 5, specify the R’, G’, and 
B’ signals used for producing bright colors. By combining the two sets of signals, 
four intensity levels for each color are produced, making 64 possible colors. The 
functions of the six bits are indicated on the following table: 


Palette Register Bit 7 6 65 4 3 r- 1 0 
Enhanced Display - - R’ G’ B’ R G B 
Color Display - - - J - R G B 
Monochrome Display - - - I Vv : - - 


Table 13.5 The functions of the six slot bits. 


3Rach color composed of three video beams, the red (R), the green (G) and the blue (B) beam. The combination 
of these components at different intensities (I) produces the whole spectrum of color. This is how color is formed 
in an RGB video display. 
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Ifanon-enhanced color display is connected to the EGA, only 4 bits are available 
to set the color, making possible 16 colors. For a monochrome display, only two 
bits are used to identify the display color intensity/nonintensity and black/video 
(white). There are additional features available with the pixel display for a 
monochrome monitor and an EGA making other video modes possible (i.e., black 
on white characters with underlining.) Please refer to other reference texts for 
additional information. 

The 16 color palette represents all the possible colors of the pixel or character 
on the screen. If all 16 colors in the color palette are set to black, nothing will be 
displayed on screen. Regardless of the value of the attribute bits, it is still mapped 
to a color of black. 

The VGA supports the EGA scheme for setting up the color palette. The VGA, 
however, also supports the gray-scale, a gradation of color, for the monochrome 
display. Therefore, when manipulating a monochrome monitor, the application 
can use the same color palette when driving a VGA monitor. 


VioGetState and VioSetState 


The state of the video adapter is determined by the display parameters that set 
the color palette, the overscan or border color, and the background intensity and 
blinking, or the lack of blinking of the foreground color. For CGA medium 
resolution mode (320 x 200), there are two pallettes, green/red/brown and cyan/ 
magenta/white, which are preset by the BIOS. For EGA and VGA, a 16-color palete 
can be set up by from 64 possible colors. Controlling the color palette of the EGA 
and VGA involves other issues concerning the type of monitor connected, the 
display plane and the palette register. Therefore, it is recommended that the 
programmer should familiarize him and herself with these issues. 

VioGetState and VioSetState return the current or set new settings for the display 
adapter, respectively. Both functions require the same parameter, a pointer toa 
memory block containing the display state information and avideo handle. When 
using VioSetState this block should contain the new settings for the video adapter. 
When using VioGetState, this block is where the current settings are returned. The 
handle is a reserved word and must be set to zero. The memory block, however, 
is a complex data structure whose make-up varies depending on the type of 
information requested or specified (this will be explained shortly). The full data 
structure looks like this: 
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struct VioState {| 


unsigned length; /* length of data 
scrucrire. = 


unsigned req_type:; /* type of raquest or set 
inrormation */ 


unsigned double_defined; /* miltiple definition */ 
unsigned palette[16]; /* color vale of palette 
GO = 15*/ 


The field req_type specifies the type of information requested or the type of 
setting. There are three types of settings or requested information: the color 
palette, the border (overscan) color, and the background intensity or foreground 
blinking status. The possible meanings and values for this parameter are: 





The parameter length specifies the length of the data structure in number of 
bytes including the field length itself. For requests concerning the color palette, 
the length of data structure should be equal to 38 bytes. For other requests, the 
fields paletteO to palette15 are not significant. Therefore, the length for request type 
of one (1) or two (2) should be equal to six (6) bytes. 

As explained earlier, the EGA provides a 16-color palette. VioGetState or 
VioSetState determine or set the values of each color in the pallette. The data 
structure VioState has 16 parameters from palette 0 to palette 1D to store the color 
values. Each parameter requires two bytes, but the only significant bits are from 
0-5. The meanings of these bits are described in Table 13.6. The OS/2 developers, 
by requesting two bytes of information for the color value were probably anticipat- 
ing future video adapters which will support more colors. 
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To request or set the color palette information, the field reg_type must be equal 
to zero (0). The field double_defined specifies the position, from 0 to 15, of the first 
palette whose color value to set or return. If dowble_defined equals five, the sixth 
color palette, the value of palette) will be set (or its current value returned) first. 
Once the first color palette is set, the function then sets the color value of the next 
palette. The number of slots in the palette which are set or whose values are 
returned is dependent on the length of the data structure defined by length. 

If length is set to 6, then only one color value can be set or reported on. If 
double_defined equals 0, then the value of the first palette slot will be set or 
determined. If dowble_defined equals 6, then the value of palette slot 7 will either 
be set or its value returned. In another example, if length is set to 10, and 
double_defined is set to 4, three color values will be set or determined starting from 
palette slot 4and continuing through 5 and 6. The following formulas summarize 
how the number of color palette slots and the starting slot is determined. 


n = number of color palette = (length- 4) / 2 


lst color palette = double_defined 
2nd color palette = double_defined +1 
nth color palette = double_defined + n 


Setting or reporting the overscan color or the status of background and 
blinking foreground are much simpler. The field length should always be set to 
6. The double_defined field stores the value of the overscan color or the status of the 
background intensity or the foreground blinking. 

To specify the overscan color information, reg_type must be set to 1, length to 6, 
and double_defined must represent the color of the border. For EGA, the border 
color also maps to a color defined by the 16-color palette. 

In order to specify the status of the background and foreground, the req_type 
must be equal to 2, the length is set to 6, and the value of double_defined represents 
the status. The values and meanings of double_defined for this type of request are 
as follows: 
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Once the foreground color is set to blinking, any characters displayed will blink 
until it is turned off. Also, if the high intensity is set for background color, any 
character displayed will remain bright until it is turned off. 


VioGetState(RequestBlock, VioHandle) 


VioSetState(RequestBlock, VioHandle) 


struct VioState far *ModeData; /* data struture of mode information */ 


unsigned VioHandle; /* reserved, must be set to 0 */ 





Cursor Control Functions 


Two types of functions control the cursor. One pair governs the position of the 
cursor, and the other pair determines its size. The position of the cursor is the row 
and column number in which it is currently located. The size of the cursor 
represents the number of video lines the cursor encompasses. 
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To determine or set the position of the cursor, functions VioGetCurPos or 
VioSetCurPos are used respectively. VioGetCurType and VioSetCurType deter- 
mine or set cursor type and whether it is hidden or not. 


VioGetCurPos and VioSetCurPos 


Both functions VioGetCurPos and VioSetCurPos expect the same parameters, the 
row and column of the cursor position, and the video handle. Both rows and 
columns start at zero representing the top rowand the left most column. The video 
handle is reserved and should be set to zero. VioGetCurPos requires two pointers 
to memory locations to which the current row and column values will be returned 
by OS/2, while VioSetCurPos expects the values where the cursor will be placed. 


VioGetCurPos (Row, Column, VioHandle) 


unsigned far *Row; /* cursor position—row */ 
unsigned far *Column; /* cursor position—column */ 
unsigned VioHandle; /* reserved for video handle */ 





VioSetCurPos (Row, Column, VioHandle) 


unsigned far *Row; /*Cursor position—row */ 
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unsigned far *Column; /* cursor position—column */ 


unsigned VioHandle; /* reserved for video handle */ 





VioGetCurType and VioSetCurType 


The cursor displayed on screen is controlled by aset of specifications: the cursor 
start line, cursor end line, the width, and the cursor attribute. The size of the cursor 
usually equals the size of one displayed character. ‘he dimension of the cursor can 
be determined by looking up the Box Size column in the tables containing the 
display mode for each adapter (pages 11-12). 

VioGetCurType and VioSetCurType return and set the characteristics of the 
cursor. Both functions expect the same parameters: a memory block containing 
the cursor characteristic and the video handle. The video handle in the current 
version of OS/2 is a reserved word and must be set to zero. The memory block is 
8 bytes long and should use the following format: 


seruct Cursoarvata | 


unsigned cur_start; /* eureor start line */ 
unsigned cur_end; /* eureor end line */ 
unsigned cur_width; /* eursor width */ 


unsigned cur_attribute; J* cursor atireibute. *F 
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Size of cursor can be varied 
within the bounds of the 


Dimensions of 
character 
cell 


en Sa ee 
li Lalita Leal Lalli Lae Let, Leal Le Le La 
ey [ae | ee | ae | ae | ce [ee fe fee (ee 





Figure 13.1 Cursor Representation 


The parameter cur_start represents the starting horizontal line of the cursor. If 
a character cell has n horizontal scan lines, the top line of the cell would be called 
line 0, and the bottom horizontal scan line would be the n-1 line. The parameter 
cur_end specifies the bottom horizontal scan line. 

The parameter cur_width specifies the width of the cursor. In graphics mode, 
the width of the cursor is measured in terms of the number of pels (picture 
elements) the cursor requires. In text mode, the width of the cursor is specified 
in columns. Unfortunately, in text mode, OS/2 only supports a cursor with a 
column width of one. The number of pels in a column depends on the box size 
of the character cell supported by the display mode and the display adapter. 

The parameter cur_attribuierepresents the attribute of the cursor, which can be 
hidden. In graphics mode, it also can have a color attribute. In text mode, the 
cursor appears according to the attributes specified for the display. If the current 
displayed color is yellow and blinking, the cursor has the same attribute. 
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VioGetCurType (CursorData, VioHandle) 


VioSetCurType (CursorData, VioHandle) 


struct CursorData far /* data structure of cursor 
characteristics */ 

*CursorData; 

unsigned VioHandle; /* reserved, must be set to 0 */ 





Example 


/* VIOCUR.C 


This program demonstrates how to use VioGetCurType and 
VioSetCurType 


oF | 


include “doscalls.h” 
include “subcalls.h” 
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main() 


Setruet CureorDaAate cursor: 
unsigned ret; 


if (ret=VIOGETCURTYPE (&cursor, 0O)) { 


printf(“\nVioGetCurType: %d”,ret); 
DOREXET( 1,0} 


erintt (“\nGuresor Startine lanes Yd“, cureor, eur start) : 


printf(*\nCursor Ending line: *d",ctiregor.etit end): 
Serintr |" \wCursor Width: {d" , cursor. cur width) ; 
printf (“\nCurser Attribute: “4d”, cursot,. cur attribute) : 
Cursor. clir_ starr — 0: 

Cursor,.cur end — G: 

cursor, cur width = @:; 


CUTSOr .cUr_Atitribute — OslrEr; 

if (ret=VIOSETCURTYPE (&cursor, 0)) { 
orintr(“\nViosetCurlType: 4d", ret): 
DOSEATIT (1,0); 

Heintt ("Va l\nThe curser as hiding: “); 

DOSSLEEP ( (long) 2000) ; 


CUuteor,.cur-Start — 4G: 


cursor.cur_end = 8; 
rursor.cur attribute — 0: 


if (ret=VIOSETCURTYPE (&cursor, 0O)) { 
printf(“\nVioSetCurType: %d”,ret); 
DOSEXIT(1,0); 

printf(“\nNotice the change in cursor size: “); 

DOSSLEEP ( (long) 2000) ; 
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Text Display Functions 


OS/2 provides numerous video API functions to display text on the video 
display as well as manipulate displayed characters and strings of characters. 
Applications can also display and manipulate the attributes of characters or strings 
of characters. 


Character and Its Attributes 


Each character is stored in the video adapter memory in a 2-byte format. The 
first byte represents the ASCII code of the character and the second byte represents 
the attributes of the displayed character. The video adapter uses the first byte to 
determine which of the 256 ASCII characters it is. The second byte is used to 
determine the foreground, background color, intensity, and blinking status of the 
character. This character-attribute combination is usually referred to as the 
displayed cell. 

The attribute byte for a character has the following bit mask values: 
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As already discussed, for the EGA the foreground color attribute of a character, 
the intensity, red, green, blue (IRGB) bits, are mapped onto a 16-color palette 
rather then reflecting the actual color value. The background color attribute is 
also mapped to the same color palette. (See the section on the color palette). 

For CGA, the following table lists the possible colors that can be produced using 
the combined values of the IRGB bits. The background can only have 8 possible 
colors from 0 to 7, because it is represented by 3 bits (RGB) instead of four like the 
foreground. 


3 2 J 0 Value 

(I) (R) (G) (B) 
Black 0 OQ 0 0 0 
Blue 0 0 0 ] ] 
Green 0 0 ] 0 Z 
Cyan 0 0 ] ] 3 
Red 0 ] 0 0 4 
Magenta 0 ] 0 1 iD 
Brown 0 ] ] 0 6 
Normal white 0 1 1 1 7 
Bright Black (non-color) 1 0 0 0 8 
Light blue ] 0 v ] 9 
Light green ] 0 ] 0 10 
Light cyan ] 0 ] 1 1] 
Light red ] ] 0 0 12 
Light magenta ] ] 0 ] 13 
Yellow (light brown) ] 1 1 0 14 
Bright white ] ] ] ] 1D 


Table 13.6 CGA Color Attribute Bits 
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A special note for MGA, when the attribute bytes specifies a blue foreground 
(O01), and a black background (000) the MGA will produce an underlined 
character. 


VioWrtTty 


Function VioWrtTty writes a character string to the display monitor in teletype 
mode starting from the current cursor position. If during the writing of the string, 
the function reaches the end of line, it continues writing the string at the beginning 
of the next line. If the function reaches the end of the screen, it scrolls the screen 
one line and writes the string at the beginning of the new line. At the end of the 
writing, the cursor is placed one character to the right of the last character of the 
string. 

VioWrtT ty expects a pointer to the character string, to the length of the string, 
and to the video handle. The video handle is reserved and should be set to zero. 


VioWrtTty (String, Length, VioHandle) 


char far *String; /* pointer t string to be displayed */ 
unsigned Length; /* length of the string */ 


unsigned VioHandle; /* reserved, set to zero */ 
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/ 


VioWrtCellStr and VioReadCellStr 


The two bytes containing the ASCII character code and its video attribute are 
called a cell. VioWrtCellStr allows the application to write a cell string, or a byte 
stream of alternating characters and attributes. Function VioReadCellStr deter- 
mines the character-attribute bytes currently displayed on the screen. Neither 
function changes the current cursor position. Please note that within a cell, the 
character byte comes before the attribute byte. 


Ist Cell 2nd Cell 
1st byte 2nd byte 3rd byte 4th byte 
lst character lst attribute 2nd character 2nd attribute 


Table 13.1 Structure of Cell String 


VioWrtCellStr expects a pointer to the cell string to be displayed, the length of 
the cell string in number of bytes, the starting row, the starting column, and the 
video handle. While writing the string, if the end ofa line is reached, the function 
continues to write at the beginning of the next line. If the function reaches the 
bottom of the screen, it stops writing the string. The function does not change the 
current cursor position. 


VioWrtCellStr (CellStr, Length, Row, Column, VioHandle) 


char far *CellStr; /* pointer to the cell string to be 
displayed */ 

unsigned Length; /* length of the cell string */ 

unsigned Row; /* starting row position */ 

unsigned Column; /* starting column position */ 


unsigned VioHandle; /* reserved, set to zero */ 





O42 Advanced Programmer's Guide to OS/2 





VioReadCellStr expects the same parameters as VioWrtCellStr. However, 
VioReadCellStr reads the cell string on the screen starting at the specified column 
and row numbers. The cell string is stored in the memory block and passed to the 
function via the pointer CellStr. The number of bytes read is specified by Length. 
The memory block should be the same length as the number of bytes read. To 
determine the exact number of bytes to be read, the programmer should remem- 
ber the string length of the string is twice as large as the number of characters 
displayed. 

Ifan end of line is reached during the reading of the cell string, VioReadCellStr 
continues to read the cell at the beginning of the next line. The function, however, 
will terminate if it reaches the end of the screen during the reading of the cell 
string. In this case, OS/ adjusts the length value for the string. 


VioReadCellStr (CellStr, Length, Row, Column, VioHandle) 


char far *CellStr; /* pointer to the cell string to be 
displayed */ 
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unsigned far * Length; /* length of the cell string */ 
unsigned Row; /* starting row position */ 
unsigned Column; /* starting column position */ 
unsigned VioHandle; /* reserved, set to zero */ 





Example 


NAME VIOREAD 
DESCRIPTION ‘Video Read Program’ 
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CODE PRELOAD SHARED 
DATA PRELOAD MULTIPLE NONSHARED 
STACKSIZE 8192 


/* VIOREAT,.C 


This program demonstrates how to use VioReadCellStr and 
VioWrtCellStr. 


It will first read the entire screen including each character 
and its attribute into a buffer via VioReadCellStrn. 


Then write the buffer to a different screen position using 
VioWrtCellStr. 


fs 


#Finclude “doscalls.h” 
#Finclude “subcalls.h” 


typedef struct cell{ 
ena els 
char attr: 

} CELE: 


typedef struct line { 
CELL 1, S8e] ; 
} LINE; 


void «lel; 
char s[80] = “Read the entire screen from postion 0, 0”; 


main () 


{ 
LINE screen[25]; 
unsigned ret, length; 


ele.) 
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length = sizeof (screen); 


strepy(s,”Read the entire screen from postion 0, 0"); 


VIOWRTCHARSTR(s, strlen(s), 


0, ce gow Fy 
oP f* col */ 
O) 3 


4f (ret = VIOREADCELLSTR( (char far *)&ecreen, 


&length, 
0, /* gtarting row */ 
0 /* startine. column */ 


OJ) 4 
printf(*\nVioReadCellStr failed %d”,ret); 
DOSEXIT (1,035 
} 
length = length - (2 * sizeof(LINE)); 


strepy(s,”then write the entire screen to postion 2, 0"); 
VIOWRTCHARSTR(s, strlen(s), 


4 /* row */ 
om f* eol *7 
O) 3 


VIOWRTCELLSTR( (char far *)éscreen, 
length, 
es 
OG, 
0); 
VIOSETCURFPOS (23 ,0,0): 
NOSEAIT (1, ti) 3 


void cls() 
{ 
char ec[2]: 


cio) = * * /* cell to replicate is a blank */ 
ell] = 7; /* with normal attributes */ 
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/* elear sereen */ 
VWIGSCROLLUP(O, 0, -1, -l. -ly. tehar far *)e,;, ©): 
VIOSETCURPOS(0,0,0):/* move cursor to heme position */ 


VioWrtCharStr and VioReadCharStr 


VioWrtCharStr writes a character string to the video monitor at a specified 
location. Function VioReadCharStr, on the other hand, reads a character string 
currently displayed on the screen. Neither function alters the current cursor 
position. 

VioWrtCharStr expects the pointer to the character string, the length of the 
string, the starting column and rowwhere the string will be displayed, and the video 
handle. The function continues writing the string at the beginning of the next line 
when an end of line is reached. VioWrtCharStr, however, terminates if the end of 
screen is reached. 


VioWrtCharStr (String, Length, Row, Column, VioHandle) 


char far “String; /* pointer to the cell string to be 
displayed */ 

unsigned Length; /* length of the cell string */ 

unsigned Row; /* starting row position */ 

unsigned Column; /* starting column position */ 


unsigned VioHandle; /* reserved, set to zero */ 
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VioReadCharStr expects the same parameters as VioWrtCharStr. The function 
reads the character string on the screen at the specified starting column and row 
position. The string is stored in the string buffer and passed to the function. The 
length of the buffer must also be specified. The length represents the number of 
bytes or characters read from the screen. The memory buffer, therefore, should 
be the same size as the length parameter. VioReadCharStr continues reading the 
string from the beginning character of the next line, if an end of line is reached. 
If the function reaches an end of screen, it terminates the reading of the string. In 
this case, OS/2 adjusts the length of the buffer to match the true length of the 
string. 


VioReadCharStr (String, Length, Row, Column, VioHandle) 


char far *String; /* pointer to the cell string to be 
displayed */ 

unsigned far * Length; /* length of the cell string */ 

unsigned Row; /* starting row position */ 

unsigned Column; /* starting column position */ 


unsigned VioHandle; /* reserved, set to zero */ 
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VioWrtCharStrAtt 


VioWrtCharStrAtt is similiar to VioWrtCharStr in terms of displaying a character 
string at a specified location on the video monitor. VioWrtCharStrAtt specifies the 
attribute of the entire string to be displayed. While VioWrtCharStr displays the 
string at the currently set screen attribute. 

VioWrtCharStrAtt expects the string pointer, the length of the string, the row 
and column of the displayed position, and the pointer to the attribute byte. 


VioWrtCharStrAtt (String, Length, Row, Column, Attribute, VioHandle) 


char far *String; /* pointer to the cell string to be 
displayed */ 

unsigned Length; /* length of the cell string */ 

unsigned Row; /* starting row position */ 

unsigned Column; /* starting column position */ 

char far *Attribute; /* pointer to attribute byte */ 


unsigned VioHandle; /* reserved, set to zero */ 
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VioWrtNChar 


Function VioWrtNChar writes 7 characters on the display screen at a specified 
location. The cursor position will remain the same at the completion of the 
function. The function expects a pointer toa l1-byte character, the number of times 
the function will write the character, the row and column number of the displayed 
position, and the video handle. During the replication of the character, if the 
function reaches the end of a line, it continues displaying the character from the 
beginning of the next line. When the function reaches the end of the screen, it will 
stop writing. 
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This function can also be used to display one character by setting the repeat 
count value to one (1). 


VioWrtNChar (Character, Times, Row, Column, Attribute, VioHandle) 


char far *Character; /* pointer to the character to be 
displayed */ 

unsigned ‘Times; /* number of times to replicate the 
character */ 

unsigned Row; /* starting row position */ 

unsigned Column; /* starting column position */ 


unsigned VioHandle; /* reserved, set to zero */ 
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VioWrtNAttr 


This function is similiar to VioWrtNChar, but instead of replicating the same 
character, it replicates the same attribute at a starting location on the screen. By 
changing the attribute of a character, the characters previously displayed will 
remain the same, but their appearance will change. This function does not alter 
the cursor position. 

The function expects a pointer to an attribute byte, the number of times the 
function will write the attribute, the row and column number of the display 
position to start changing the attribute, and the video handle. If during the 
replication of the attribute, the function reaches the end of a line, it continues 
switching the attribute at the beginning position of the next line. If the function 
reaches the end of the screen, it stops writing. 


VioWrtNAttr (Character, Times, Row, Column, Attribute, VioHandle) 


char far *Attribute; /* pointer to the attribute to be 
displayed */ 

unsigned Times; /* number of times to replicate the 
attribute */ 

unsigned Row; /* starting row position */ 

unsigned Column; /* starting column position */ 


unsigned VioHandle; /f* reserved, set to zero */ 
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VioWrtNCell 


VioWrtN Cell is a combination of the functions VioWrtNChar and VioWrtNAttr. 
It replicates a cell (character-attribute pair) nm number of times on the display 
screen at a specified starting location. It does not alter the cursor position. 
Remember that a cell is two bytes long with the character value preceding the 
attribute byte. 

The function expects a pointer to the cell, the number of times the function will 
write the cell, the row and column number at which it will start writing, and the 
video handle. During the replication of the cell, if the function reaches the end 
of line, it continues writing the cell at the beginning position of the next line. If 
the function reaches the end of the screen, it stops writing. 


VioWrtNCell (Cell, Times, Row, Column, Attribute, VioHandle) 


char far *Cell; /* pointer to the cell to be displayed */ 

unsigned Times; /* number of times to replicate the 
attribute */ 

unsigned Row; /* starting row position */ 

unsigned Column; /* starting column position */ 


unsigned VioHandle; /* reserved, set to zero */ 
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Example 


/* VIOWRT.C 


This program demonstrates how to use VioWrtNChar, VioWrtNAttr 
and VioWrtNCell 


ey 


Finclude “deacalls.h” 
#Finclude “subcalls.h” 


define 
#define 
define 
4tdefine 


+#define 
define 


FBLUE 
FGREEN 
FRED 
INTENSE 


BBLUE 
BGREEN 


1 
Z 
4 
8 


16 
32 


/* foreground blue */ 

‘ie green */ 

ce red */ 

/* intensity on/off switch */ 


/* background blue */ 
oe green */ 
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#fdefine BRED 64 he red */ 
#tdefine BLINK 123 (* blinking switeh */ 


typedef struct cell{ 
ehar ch: 
ehar attrib: 
) CHE: 
void els{); 
main() 
{ 
char Attrib; /* character Attribute */ 


char s[80]: 


CHL cell. 


sttepy(s,.”*The tirst line will blink “); 


ele ty: 
VIOWRTCHARSTR(s,strilen(s), 0,0, 0); 


Attrib = BLINK | FRED | FGREEN | FBLUE; 


VIOWRTNATTR(&Attrib, 
80, /* number of times */ 
Oy /* starting row */ 
0, dee and column */ 
O}% 


Ceall.ch = *K’s 
eel) <ettrcib = ATtrib: 


strepy(s,”The 4th line will be a series of blinking X’s”); 
VIOWRTCHARSTR(s,etrlen(s),1,10,0) ; 
VIOWRTNCELL (&cell, J* @611 *ke be written */ 

30, 

3; 

oe 

Os 
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VIOSETCURPOS (23,0,0); /* move cursor to home position */ 


void cls() 


{ 


enar e[ 2): 
e[O) = * *s /* call te replicate is 4 blank */ 
c[l] = FRED | FGREEN | FBLUE; /* with normal attributes */ 


/*-clear screen */ 
VYIOSCROLLUE(O, 0, =, “1, “ly teber far *je, 0}; 
VIOSETCURPOS (0,.0,0) /* move cursor to home position */ 


} 


Screen Scrolling 


OS/2 provides capabilities for scrolling the screen up, down, left and right using 
functions VioScrollUp, VioScrollDn, VioScrollLf, and VioScrollRt, respectively. 
Each function expects the same parameters: the positions specifying the dimen- 
sions of the area to be scrolled, the number of lines to insert after the scroll area 
(the number of lines to scroll up or down, left or right), and the cell (character- 
attribute) pair which the function will use to fill the area left blank after the 
scrolling. A cell consists of two bytes containing the character value and its 
attribute value. To leave this area blank, the cell should be set to be a blank 
character ( ). 

The position of the area to be scrolled is identified by the top row, left column, 
right column and bottom row numbers. The range for the row values is from 0 to 
94, and for the column values it is from 0 to 78. A value of zero for the row and 
column represents the top-and-left-most corner of the screen. If the values of any 
row or column exceed the maximum values within this range, OS/2 will use the 
maximum value for the function. 

For scrolling up and down, the number of lines represents the number of 
horizontal lines that will be inserted after or before the scrolled area, respectively. 
When the application scrolls left or right, the number of lines represents the 
number of columns that will be inserted to the right or to the left of the scrolled 
area, respectively. This parameter is equal to the number of lines to be scrolled in 
any direction. If the number of lines is equal to zero, the specified area will not be 
scrolled. 
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VioScrollUp and VioScrollDn 


VioScrollUp and VioScrollDn scroll the specified area on the display up and 
down. 


VioScrollUp (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle) 


VioScroliDn (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandie) 


unsigned TopRow; /* the top row of the area to be 
scrolled */ 

unsigned LeftCol,; /* the left column number of the area to 
be scrolled */ 

unsigned BotRow; /* the bottom row number of the area to 
be scrolled */ 

unsigned RightCol; /* the right column number of the area 
to be scrolled */ 

unsigned Lines; /* the number of lines to the area is to be 
scrolled* / 

char far *Cell; /* pointer to the cell that will fill the 


blank area */ 


unsigned VioHandle; /* reserved word, must be zero */ 
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VioScroliLf and VioScroliRt 


VioScrollILf and VioScrollRt scroll the specified area on the display to the left 
or the right, respectively. 


VioScrollLf (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle) 


VioScrollRt (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle) 


unsigned TopRow; /* the top row of the area to be 
scrolled */ 
unsigned LeftCol; /* the left column number of the area to 


be scrolled */ 
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unsigned BotRow; /* the bottom row number of the area to 
be scrolled */ 

unsigned RightCol; /* the right column number of the area 
to be scrolled */ 

unsigned Lines; /* the number of columns the area is to 
be scrolled* / 

char far *Cell; /* pointer to the cell that fills the blank 
aréa */ 


unsigned VioHandle; /* reserved word, must be zero */ 
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Clearing The Screen 


Any of the scrolling functions can be used to clear the screen by specifying the 
TopRow and LeftCol to zero, the BotRow, RightCol, and Lines to negative one (-1), 
and the cell to a blank character ( ) with a normal video attribute. This method 
of clearing the screen can be used in any of the text or graphic display modes. If 
the cell is any other character and the display mode is in text mode, the entire 
screen will be filled with that character. 


Example 1—List.c 


J* LIST .C 


This program demonstrate how to use disk I/O and VIO functions. 
lt will mot take advantage of O8/2 multi-tasking capabilitias. 
The program also demonstrates how to clear the screen in 0S/2 
(look at routine CLS.) 


This program will simply display an ASCII text file on the 
screen, 


“y 
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4tinclude 
include 
4Finclude 
include 


#define 
define 
#define 
#tdefine 


+#define 
+#define 
+#define 


+#define 
+#define 
+#define 


+#define 
+#define 
+#define 


+#define 
+#define 


void dis 
void out 
void els 


/* globa 


main (ar 
Int arec 
char *ar 


{ 


"Stato. h” 
“qogtalle.h” 
“subcalia.h” 
"doe. D- 


O_FAIL Ox0000 /* constant for DosOpen */ 

QO _OPEN Ox0001 

O_ REPLACE 0x0002 

O_CREAT Ox0010 /* ereate if file does not existe */ 


DENY_READ 0x0010 /* sharing mode */ 
DENY_WRITE 0x0020 
DENY_NONE 0x0040 


READ ONLY Ox0000 /* Access mode */ 
WRITE ONLY 0Ox0001 
READ WRITE 0Ox0002 


CR OxO0D 
Le OxO0A 
TAB Ox09 
BUFLEN AI 2 

STACKS IZE 4000 


play(); 
disp (ys: 
Lis 


l variable */ 


gc,argv) 


avi]; 


char far *puri: 
char far *but2Z: 
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unsigned Selectorl, Selector2; 


/* parameters for DosOpen */ 
unsigned fdl, 42+ ;* tile deseripter 1. and 2 *¥ 
unsigned ActionTaken; 


long fsizel, fsize2; i Tile -@ize "7 
long 1; /* temporary war */ 


long bytesreadl, bytesread2; 


unsigned buflenl; 
unsigned buflen2; 


char far *s; 
unsigned ret,i; 
unsigned thread_id; /* param for DosCreateThread */ 


imsigned stopl, stop2; /* flags to detarmine when to stop 
reading */ 


if (area < 2) 1 
printr(“\acemnand Format: LIST <tile cane» }: 
prines ("ay eg.: LIST autoexec.bat”): 
DOSEXIT (1,0); 


/* open file */ 


ret = DOSOPEN((char far *)argv[1], 
(unsigned far *)&fdl, 
(unsigned far *)&ActionTaken, 
Os /* N/A WHEN OPEN AN EXISTING FILE */ 
0, f* same as above */ 
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O_OPEN, 
DENY_NONE | READ_ONLY,/* open mode */ 
OL); 


if (ret) { 
printf(“\nDosOpen failed: %s %d”,argv[1],ret); 
DOSEXIT(1,G): 


/* using DosChsFilePtr to get file size */ 
DOSCHGFPILEPTIR Cid , 
ls» 
Di /* move from the eor */ 
(lene far *)G¢fisizel) 
ret = DOSCHGFILEPTR (fdl1, 
OL, 
oP 
(longs far *)&1); 


re. 


butlenl = lant) tfeaizel 4 
J/* allec the memory buffer for the file */ 
/* this will make it impossible for */ 
/* the program to process files larger */ 
/* than 64K. This is only an example of */ 
/* how to display a file, */ 
/* we will provide a better examples of the */ 
/* same. progtam in later chapters using */ 


ret = DOSALLOCSEG (buflenltl, 
(unsigned far *)&Selectorl, 
OQ}; 


if (ret) { 
printf (“\nDosAllocSeg failed %d”",ret); 
DOSEAIT (1,0) 3 
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FP SEG(bufl) = Selectorl: 
FP OFF(bufl) = 0O; 


/* read the contents of the files */ 


elled}s 


ret = DOSREAD(fdl1,/* read from file 1 */ 
(ehar tar *) but, 
buflenl, 


(unsigned far *)&i); 


*(buftitbutleni) =" \0': 


if (rat) 4 


printf (*\akrror reading “Gs error: Yd” 


arev[1], ret); 
DOSEXIT (1,0); 


/* read into buffer 2 */ 


/* assign argument to the thread stack */ 


display {buti); 


DOSCLOSE (fal): 
DOSFREESEG(Selectorl); 


void display (buf1) 
char tar *burl; 
{ 


enar far “start! : 
char tar *e@l; 


static int count=0:/* line count */ 
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setartl = el = busi: 


while (1) { 
{/* determine the start of line. */ 
if (*sl == (char) LF ) { 
‘ie “As f° ay Brert of line */ 
SOumtT rs /* then display previous line */ 
SuULniosp letarcl): 
start] = tralt (§* point to the mext line */ 
if (*e1++ == °\G6") 
break; 
} 
} 
youd cle() 
{ 
enar @|2]: 
e[O0] =* *; /* gall to replicate is a blank */ 
e[1] = 7; /* with normal attributes */ 


/* elear screen */ 
VIOSCROLLUP(O, ©, -<1, -1l, -l, tehar tar *Je,. G): 


unsigned lstrlen(s) 
Cnar tar *e: 
{ 

Lie at 

ehar far *t; 


c=. 2 
1 =O; 
woile (*ett 1="\0") 


ie aa 
feturn (4) > 
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--~ — 


void outdisp(s1) 
ener tar “sl: 


{ 


Lik As 
char temp (40, «; 
Statae 2nt cow’: 


/* APT funetion to display an ASCII string on the screen */ 


VIOSETCURPOS (rowt+,/* row */ 
G. /* eolum */ 
0); 

VIOWRTTTY ((char far *)el, 
latrlen(el), 
O}s 


if (row + 23) { 
strepy(temp,”Press any key to continue”) ; 
VIOWRTCHARSTR( (char far *)temp, 
strlen(temp) , 


row, 

Oy aS 

c = ‘\0’; 

while (c == ‘\0’) 
ec = getch():; 

row = QO; 


celal}: 
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Example 2 - Box.C 


/* BOX.C 


This example demonstrates several VIO functions to output char- 
acter to screen using VIOWRTNCHAR, VIOWRTCHARSTR, VIOGETCURPOS, 
VIOSETCURPOS 


= 


#include “malloc.h” 
ffinclude “stdio.h” 
include “doscalls.h” 
include “subcalls.h” 


4tdefine STACK SIZE 1024 


+#define VERT 
4#tdefine HORZ 
define UPRT 
define LWLF 
#tdefine LWRT 
+#define UPLF 


/* definition for drawine box */ 


Mm PWN F OO 


void far thread2{): 
void box(); 
vToLd clet)-: 


main() 
{ 
/* DOSCREATETHREAD arguments */ 


char *new_stack; 
unsigned thread_id; 
unsigned ret; 

char s[80]; 

ehar <c% 

ce comes Me 
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if ((new_stack = malloc(STACK_SIZE)) = 0) { 
orantt("\\nmalloc(), not successful”) ; 
DOSEXIT (1,1) 
} 


new stack += STACK SIZE; /* put the pointer to the top ef stack 
| 


elet js 


/* start another thread */ 
if (ret = DOSCREATETHREAD (thread2, 
(unsigned far *) &thread_id, 
new_stack) ) 


{ 
printf(“\nDosCreateThread failed: %u”,ret); 


DOSEXIT(1,2) + 
} 


pot3.5,10,60) + 
strepy(s.”Primary thread display ASCII character from 1-128"); 


VIOWRTCHARSTR(s,strlen(s),4,6,0); 
For (150; i < 128: itt) { 


c = (char)i; 
VIOWRTNCHAR (&c, 
th /* number of time */ 
. {* Row */ 
10, /* column */ 
0): 


DOSSLEEP (( long)10) ; 


DOSSLEEP ( (long) 5000) ; /* the primary thread will sleep for 5 
seconds */ 

DOSEXIT(1,0); 

} 


/* thread #2 will print a message and exit */ 
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woid far thread? () 
{ 

char s[80]: 

ic he 

char e¢: 

box (12,5,20,30)- 

strepy(s,”Thread #2 displaye ASCII character from 128- 
256"): 

VIOWRTCHARSTR(s,strlen(s) ,13,6,0): 


for (4-128; j+ty 7< 256) { 


e = (enar)4 
VIOWRTNCHAR (&c, 
1 /* number of time */ 
15; /* Row */ 
io. /* column */ 
0) 


DOSSLEEP ((long)10); 
DOSEXIT (0,0) : 
void box(x,y,xl,y1) 
unsigned x,y,xl,yl; 
{ 
static char border[6é] ={[ *\eB3",* \xC4',*\e2BF’,*\eCO',’ \eD9o’', 
 \oDA? } 3 


1Her 4 
int row, column: 


VIOGETCURPOS (&row, &column,0O); 


VIOWRTNCHAR (&border [HORZ] , (yl-y-1),x,yt1,0); 
VIOWRTNCHAR (&border [HORZ] , (yl-y-1),xl,yt1,0); 


for (i=eFl:i < xi:itt) { 
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VIOWRTNCHAR (&border [VERT] ,1,i,y,0); 
VIOWRTNCHAR (&border [VERT],1,i,y1,0); 
} 
VIOWRTNCHAR (&border [UPRT] 
VIOWRTNCHAR (&border[LWRT] , 
VIOWRTNCHAR (&border[UPLF] , 
VIOWRTNCHAR (&border[LWLF] , 


VIOSETCURPOS (row,column,0O):; 
/* move the cursor back to */ 
/* original position */ 


void cls() /* clear sereen */ 

{ 
char « [2): 
eLol = “ *s %* @61) te repligate ie a blank */ 
c[l] = 7; /* with normal attributes */ 


f* elear screen */ 
VIOSCROLLUP(O, O, <1; -1, -1, tehar far Fie, GG): 


ANSI Support Functions 


OS/2 provides two functions for ANSI support. VioGetANSI determines 
whether ANSI escape sequence handling is currently on or off. VioSetAnsi turns 
ANSI support on or off. Before ANSI support can be turned on, the ANSI device 
driver must be loaded in the configuration file, config.sys. ANSI support allows the 
video monitor to act as an ANSI terminal by accepting ANSI escape sequences. 


VioGetANSI and VioSetANSI 


VioGetANSI returns an indicator value to identify whether ANSI support is 
turned on or off for the current screen group. A returned value of one indicates 
that ANSI support is on, and zero indicates that it is off. 
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VioGetANSI (Indicator, VioHandle) 


unsigned far *Indicator; /* returned indicator value */ 


unsigned VioHandle; /* reserved word must be zero */ 





VioSetANSI (Indicator, VioHandle) 


unsigned Indicator; /* indicator value */ 


unsigned VioHandle; /* reserved word must be zero */ 
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Chapter 14 





Keyboard Functions 


Just like the video subsystem, the keyboard subsystem is implemented 

using dynamic link libraries. Its API functions are found in the dynamic 
link library, KBDCALLS.DLL. The BKSCALLS.DLL library contains the base sub- 
system calls used by the API keyboard functions. Separating subsystems from the 
OS/2 kernel in this manner will allow future keyboard devices to be supported 
without having to change the operating system kernel. 

The OS/2 keyboard subsystem not only provides applications with the ability to 
receive basic keyboard input, but also provides a wide variety of complex keyboard 
functions. These can be easily identified because their names are all prefaced with 
the letters “KBD.” Using the basic keyboard functions OS/2 applications can 
receive an ASCII code, scan code, shift states, and a time stamp for every key 
pressed. Advanced keyboard services include support for code page switching, 
necessary for multi-lingual applications. They provide keyboard monitor services 
needed for trapping “hot-key” sequences (used to provide background processes 
with TSR-like capabilities) , and facilities that allow applications to replace the OS/ 
2 provided keyboard functions with their own. Applications can also bypass 
keyboard subsystem entirely and make direct calls to OS/2 keyboard device drivers 
using IOCTL function calls (See Chapter 18). 

OS/2 introduces a major improvement over DOS with the inclusion of key- 
board monitor services. These keyboard monitor services allow several OS/2 
applications running in the background to monitor the keyboard inputs without 
resorting to interrupt handlers. This allows multiple TSR type programs to be 
easily implemented in the OS/2 environment. Under DOS, multiple TSR 
applications using interrupt handlers to wait for “hot keys” results in these 
applications fighting to receive keystrokes in a chaotic fashion. The OS/2 
developers recognized the convenience and flexibility TSR applications provide, 
and devised special system services that make it easier to write TSR applications 


O S/2 provides keyboard support for its applications as a separate subsystem. 
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compatible with OS/2’s structured environment. We will discuss the implemen- 
tation of keyboard monitors, and TSRs in Chapter 20, Device Monitors. 

OS/2 applications have many options for customizing or even replacing the 
OS/2 keyboard subsystem. They can specify a few of their own functions or they 
can replace all OS/2 supplied functions. Applications can also bypass the the OS/ 
2 keyboard subsystem altogether and specify their own. In this case the application 
must run as a dedicated system (it can be the only application running), because 
the OS/2 keyboard subsystem resolves the conflicts associated with having mul- 
tiple applications use the same keyboard. We will discuss these services in Chapter 
17. 

Not many OS/2 applications need to substitute their own keyboard subsystem, 
replace OS/2 functions with their own, trap key sequences from the background, 
or substitute code pages for foreign language applications. Consequently, we'll 
discuss these advanced keyboard features in later chapters. The primary concern 
for most applications is simply receiving and processing the keystrokes entered by 
the user. Even with regard to these basic features OS/2 offers substantial 
advantages to the programmer. An application can receive not only the completed 
ASCII code that is translated from a keystroke combination, but can also receive 
the scan codes associated with an individual keystroke, monitor and set the shift- 
states of certain special keys (such as the Alt or Shift key) ,and manipulate a unique 
time-stamp associated with each keystroke. These services are provided to 
applications by the OS/2 keyboard functions, which are quick, and easy to use. 
Programmers can accomplish the preceding functions without resorting to inter- 
rupts or other complex programming techniques. This chapter covers these 
crucial “basic” keyboard functions that allow an application to receive inputs from 
the keyboard, and to manipulate the keyboard status. 


Scan Codes and Shift States 


Remember that every OS/2 application executed under the Session Manager 
runs within its own screen group. Each screen group provides a logical keyboard 
buffer and logical video buffer. Applications do not receive keyboard input directly 
from the physical keyboard, but from this logical keyboard buffer. Whenever an 
application is selected to run in the foreground, the physical keyboard is directly 
associated with its logical keyboard buffer. The process of binding the two is usually 
referred to as having a program obtain the keyboard focus. 

In order to understand how to use the OS/2 services that allow programs to 
receive keyboard input, we need first to discuss how keystrokes are received and 
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translated. Each key on the keyboard is identified by a code, the scan code. 
Whenever a key is pressed, the keyboard sends the scan codeto the ROM Bios. When 
the key is released, a release code is also sent to the Bios handling routine. The 
release code is always the sum of the key scan code plus 128. The Bios translates 
the codes received into the actual ASCII code manipulated by a program. 

The status of certain other keys also determines the ASCII code that is generated 
when a key is depressed. These special keys are either shift keys such as the Alt, 
Shift, Cntrl, and SysReq keys, or toggle keys like CapsLock, NumLock, ScrollLock, 
and the Ins keys. An examination of the shift states of these keys determines whether 
they are depressed or not, or whether the toggle which they represent is set or clear. 
For example, if the key representing the letter “z”on the keyboard is depressed a 
certain scan code is transmitted to the Bios. However the ASCII code that is 
generated also depends on the state of the Shift key. Ifit is depressed the ASCII 
code for an uppercase “Z” is generated, if itis not, the ASCII code for a lowercase 
“z” is generated. The status of the toggle keys also has a bearing on which ASCII 
code is generated when a key is depressed. In the previous example if the CapsLock 
toggle key were also set then the ASCII code for an uppercase “Z” would be 
generated when the “z” key was depressed, and the ASCII code for a “z” would be 
generated if the “z” key was depressed while the Shift key was also down. 

OS/2, like DOS, has an extended ASCII code set that allows it to incorporate 
the inputs of keystrokes such as functions keys, keys on the keypads, and codes for 
keys depressed in combination with the Alt and Cntrl keys. All told, 256 ASCII 
codes can be assigned to keystroke combinations. 

OS/2 also supports the double-byte character code set (DBCS) which is used to 
create characters for foreign languages with more, or different, characters than the 
English language. This method requires several combined keystrokes to generate 
one character. In order to implement DBCS, OS/2 provides an interim character 
flag which is attached to each keystroke. If the interim character flag is set, the 
application accepts multiple keystrokes until it recognizes that a displayable 
character code has been entered from the keyboard. When the final keystroke in 
the sequence has been received, the interim character flag is turned off. 


Logical Keyboard Buffer and Keyboard Handle 


The Session Manager automatically provides each session with a default logical 
keyboard buffer. Whenever the session is selected or otherwise running in the 
foreground, its logical keyboard buffer is automatically bound to the physical 
keyboard. This is called getting the keyboard focus. An application running within the 
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session then has several choices when it comes to receiving keyboard input. It can 
simply use the STDIN handle to receive TTY or character-based data from the 
keyboard. If the application needs to read scan codes and shift states, it can use the 
functions introduced in this chapter. Using these functions to access the logical 
keyboard buffer is a simple enough matter. A thread within the application simply 
issues any of the KBD API functions with the default keyboard handle 0. There is 
no need to explicitly obtain a handle from the operating system (using KbdOpen) 
in order to access the default logical keyboard buffer. . | 

The above method of doing keyboard input is adequate when using the 
application I/O scheme recommended in Chapter 12. To recapitulate briefly, we 
suggest that applications be written in such a way that a single foreground process 
be dedicated to doing all basic I/O. The keyboard device driver automatically 
serializes all KBD calls (it only handles one call at a time). However, if the 
programmer wishes to share the keyboard input duties among multiple threads 
within that process, some form of synchronization has to be set up in order to 
maintain the integrity of the keyboard data. 

The keyboard subsystem, unlike the mouse or video subsystems, allows for 
multiple logical keyboard buffers to be created per session. Multiple processes or 
applications can each do their own keyboard input. There is no need to worry 
about the integrity of the keyboard data, because each process wishing to receive 
keyboard input has its own logical keyboard handle. However, applications which 
implement keyboard input in this manner have to concern themselves explicitly 
with getting the keyboard focus. In other words each process within a session that 
wishes to receive keyboard input has to open a logical keyboard buffer (using 
KbdOpen), and then obtain the focus of the physical keyboard (bind the physical 
keyboard to its logical keyboard buffer) with KbdGetFocus before it can issue any 
KBD calls. Only processes in the foreground session may issue KbdGetFocus. If 
a thread in a background session issues this call, it is blocked until its session is 
switched into the foreground. If another process (another logical keyboard 
buffer) already has the keyboard focus, then the KbdGetFocus call is blocked until 
the keyboard focus is released by the other process using KbdFreeFocus. When 
multiple processes within a screen group are all doing their own keyboard I/O via 
separate logical keyboard buffers, then the keyboard focus is shared among them 
in the manner of a serially reusable resource (SRR). The keyboard focus is 
obtained using KbdGetFocus, which prevents any other process from getting the 
keyboard focus. Focus is relinquished using DosFreeFocus (this gives another 
process the opportunity to get the keyboard focus). If the physical keyboard is 
already bound to another logical keyboard, the thread issuing a process’ Kbd- 
GetFocus call is blocked until the other process issues KbdFreeFocus. If multiple 
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procesess are blocked, there is no way to predict which process will get the key- 
board focus once it is free. If no other KbdGetFocus call is pending when a 
KbdFreeFocus call is issued, then the physical keyboard focus reverts back to the 
default keyboard buffer. When a process no longer needs to receive input from 
the keyboard, it should close its logical keyboard handle using KbdClose. 

When a session is first created, the Session Manager uses KbdOpen and 
KbdGetFocus, to obtain a default logical keyboard for the session. When a thread 
issues a KBD function using the default handle (0), the Session Manager translates 
this into the actual keyboard handle returned by KbdOpen. When a session is 
closed, the default keyboard handle is deleted by the Session Manager with 
KbdClose. In general, applications which dedicate a single process for receiving 
keyboard input do not have to worry about issuing any of these keyboard 
serialization calls. They simply issue KBD functions with the default keyboard 
handle 0. If such applications run under the presentation manager, the PM will 
take care ofall the synchronization required to share the keyboard among multiple 
applications running in the same screen group. 


Keyboard Access 


The keyboard access functions are only used by applications which wish to open 
additional keyboard handles for a session, or which wish to use a keyboard handle 
other than the default one created for a session by the Session Manager (handle 
0). These applications must issue KbdOpen to receive the handle(s) of a logical 
keyboard buffer(s) and KbdGetFocus to focus or bind a logical keyboard buffer 
with the physical keyboard before using any other keyboard functions to receive 
data from the physical keyboard. However, if a thread tries to issue KbdGetFocus 
from a background session it is blocked until its session is switched into the 
foreground. When a process is not actively receiving data from the keyboard, it 
should release the focus of the physical keyboard using KbdFreeFocus, so another 
process can obtain the keyboard focus. Once a process is finished with a logical 
keyboard buffer, it should issue KbdClose to delete the logical keyboard buffer 
(see the previous section for a full discussion of the issues involved). 


KbdOpen and KbdClose 


The function KbdOpen gives a process access to a new logical keyboard buffer. 
The function requires one argument: a pointer to memory location to which 
OS/2 returns a keyboard handle, which the process uses for subsequent access to 
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that logical keyboard buffer through KBD API. KbdClose deletes a logical 
keyboard buffer (handle). Any further attempts to access the logical video buffer 
with a closed handle will result in an error. KbdClose also requires a single 
parameter: the keyboard handle representing the logical keyboard being closed. 


KbdOpen (KbdHandle) 


unsigned far *KbdHandle; /* pointer to the keyboard handle to be 
returned */ 





KbdClose (KbdHandle) 


unsigned KbdHandle; /* the keyboard handle to be removed */ 





KbdGetFocus and KbdFreeFocus 


The functions KbdGetFocus and KbdFreeFocus are used, repectively, to either 
bind a specified logical keyboard buffer with the physical keyboard buffer, or 
dissolve the bond between a logical keyboard buffer and the physical keyboard. 
Only one KbdGetFocus call can be in effect at one time during the foreground 
session. Multiple KbdGetFocus calls are queued. If there are no KbdGetFocus calls 
pending when KbdFreeFocus is issued the keyboard focus reverts back to the 
default logical keyboard. The keyboard focus can also be gotten for the default 
logical keyboard 0. This call can only be made from a foreground session. 

Both functions require the same parameter, a keyboard handle, for a logical 
keyboard buffer to which the physical keyboard is to be bound or unbound. This 
keyboard handle was either returned by KbdOpen or the default keyboard handle. 
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KbdGetFocus (KbdHandle) 


KbdFreeFocus (KbdHandle) 


unsigned far *KbdHandle; /* pointer to the keyboard handle for 
which the focus is to be obtained or 


released* / 





Keyboard Inputs 


Whenever a key is pressed, using KbdCharIn or KbdPeek, the ASCII code, the 
scan code, the shift states of the shift and toggle keys, and the time when the key 
was pressed can be determined by an application. KbdCharIn removes the 
keystroke from the keyboard buffer, while KbdPeek returns the values for a 
keystroke, but does not remove it from the keyboard input buffer. KbdStringIn 
receives an entire string of ASCII characters from the keyboard. The application 
can also clear the keyboard buffer, getting rid of all keystrokes entered by calling 
KbdFlushBuffer. All these functions require a keyboard handle. For applications 
that only have one process receiving keyboard input, the default keyboard handle 
zero (Q) can be used. 


KbdCharin and KbdPeek 


Every time a key is pressed, an associated data packet is stored in the keyboard 
buffer. The keystroke is defined by this data packet, which contains information 
about the keystroke such as its scan code, the shift states that were in effect when 
the key was depressed, and a time-stamp. By using KbdCharIn or KbdPeek, an 
application can receive the ASCII character code that is calculated from a key’s 
scan codes and the shift states that are currently in effect. These functions also 
return the entire contents of each keystroke’s data packet. 
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KbdCharIn removes the data packet associated with the keystroke from the 
keyboard buffer and erases all traces of the keystroke. KbdPeek returns all the 
information associated with a data packet, but does not remove it from the 
keyboard buffer. Because the data packet is not removed from the keyboard 
buffer, the next call to either of these keyboard input functions yields the same data 
packet (until the keystroke is removed with KbdCharIn or the buffer is flushed). 
When using these two functions for keyboard input, the characters or ASCII value 
are not echoed on the video screen. 

When a keystroke is an extended ASCII character, KbdCharIn and KbdPeek 
return both bytes of the extended code. For characters using the double byte 
character code set (DBCS), two instances of KbdCharIn are necessary to obtain the . 
entire character code. 

Both functions expect similar parameters. KbdCharIn requires: a pointer to a 
data structure containing the keystroke data packet, and the ASCII code that is 
calculated from this information; the wait option; and the keyboard handle. 
KbdPeek only requires the data structure and the keyboard handle without the 
wait option. The wait option is specified by the variable JOWazt. It indicates 
whether the function waits until a keystroke is entered or return immediately if the 
keyboard buffer is empty. 

The data structure is a 10-byte memory block which must have the following 
format: 


srruct Charbata { 


char ASCIIcode: /* ASCII eode of the 
character */ 

char ScanCode; /* sean code of the key 
pressed */ 

char NLSStatus; /* pational language support 
(NLS) statue */ 

char NLSShiftstatue: ce Woe shite state: */ 

unsigned ShiftState; ;* ghee Strasse *y 

unsigned long time; /* time stamp of the 


keystroke */ 


The parameter ASC//Code represents the returned ASCII code of the character 
or the keystroke sequence translated from the scan code and the shift state values. 
The parameter ScanCode indicates the scan code of the key pressed. The first byte 
of extended ASCII characters is returned in the paramater ASC//Code, it is always 
0 x 00 or 0 x Oe. The second byte is returned in the ScanCode parameter. For 
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example, if the function key “F1” is pressed then ASC//Code would be “0”, and 
ScanCode “3b”. | 

The NLSStatus and NLSShifiStatus stands for National Language Support Status 
and Shift Status respectively. This informations is used for DBCS support. For 
those languages which do not use DBCS, like English, these values are always zero. 
As explained on page 5, DBCS uses a combination of several keystrokes to form a 
single character of the foreign language. The NLSShifiStatus is reserved and always 
zero. The NLLSStatus determines the status of a character—whether it is an 
interim key or the final key of a multi-keystroke sequence required to generate a 
character. The bit mask values for NLSStatus are as follows: 





The shift states are returned in a 2-byte (WORD) or unsigned variable. The bit 
mask values of this variable represent the shift states of the shift keys and the status 
of the toggle keys on the keyboard when any other key is pressed. The following 
list identifies the significance of each bit of the ShzftState variable. The meaning 
listed represents the significance of the bit when it is set, otherwise the shift key is 
not down or the toggle key is not on. 
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The parameter TimeStamp is a 4-byte (Double word) memory block or a long 
value indicating the time that the keystroke sequence was entered. This parameter 
contains four values representing the hour, minute, second, and hundredth of a 
second components of the time stamp. The format of this memory block is as 
follows: 


struct timestamp { 
byte hour; 
byte minute; 
byte second; 
byte hundredth; 


KbdCharin (CharData, lOWait, KobdHandle) 


KbdPeek (CharData, KbdHandle) 


Keyboard Functions 583 


struct CharData far *CharData; /* pointer to returned keystroke 
information */ 
unsigned lOWait; /* wait option */ 


unsigned KbdHandle; /* pointer to keyboard handle */ 
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Example 
/* KBDCHAR.C 


This program demonstrates how to use KbdCharIn and KbdPeek. The 
only difference between the two calls are: 


KbdPeek,the keystroke is not removed from the keyboard buffer. 
KbdPeek, do not have a WAIT or NOWAIT parameter. 


This program will display the ASCII code, scan code, shift 
status, NLS Shift status, and the shift state for all the key- 
strokes. 

For extended ASCII code (there are two bytes of informa- 
tion), OS/2 will returns either a 0x00 or Ox0E for the ASCII 
code and the second byte is stored in the scan code. Except for 
function keys, key pads, and special keys such as SysReq, Scroll 
Lock, Pause, the second byte is the scan code of the key. 


To determine the status of the shift, cntrl, or alt keys, use 
the returned shift state parameter. 


For example: 
- if Fl is pressed, 
ASGII code: - 0200, scan code: 3B. shitt state: Ox000G. 


= Tor Baile“ E1, 

ASCIIL code: 0x00, scan code: 54, shift state: Ox0002. 
= Pei Ger ie# 1 , 

ASCII code: 0x00, scan code: 5E, shift state: Ox0104. 
~ For Alt-Fi, 

ASCII code: 02x00, scan code: 68, shift state: Ox0Z08. 


- For Catri-Alt-F1, 
ASCII eade: 0x00, scan code: 68, shiit state: Ox0S0C. 


* #£oe Urerl-Ale-Shiit-FL, 
ASCII code: Ox00, scan code: 60, shILTt state: Ox030F. 


For more keystroke values, you can run this program and try each 
of them out. a | 
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include “doscalls.h” 
include “subcalls.h” 


define 
+#define 


4tdefine 
+#define 
define 


define 
define 
define 
define 
define 
define 


WAIT 0 /* definitions for KbdCharin */ 
NOWAILT 1 

CNTRL 0x0004 /* either cntrl key is down */ 
ALT 0x0008 /* either Alt key is down */ 
K_Q 0x0010 /* scan code for the key @ */ 
VERT 0 /* definition for drawing box */ 
HORZ 1 

UPRT 2 

LWLF 3 

LWRT 4 

UPLF 5 


void WriteScreen(char far *s,unsigned x, unsigned y); 


TOLLE € 
void b 


{ main 


lati 
ext) 


() 
struct KeyData kbddata; 
unsigned ret; 


char s[80]; 


/* we will use the default keyboard handle. This is the 
preferred method of getting data from the keyboard. */ 


KBDFLUSHBUFFER (0) ; /* flush the buffer */ 
ele): 

box (2, 44,12,75); 

while £13 


if (ret = KBDCHARIN(&kbddata, NOWAIT, 0)) { 
orint?® (* \nKBDCHARIN tailed: %d”", ret) - 
DOSEZIT(I.0)- 
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WriteScreen((char far *)”Key strokes 
Monitere”,3,50): 
WriteScreen( (char far *)”Prese Cntril-Alt-Q 
to gui" ii, aes 


sprintf(s,”ASCII code: %02X”, (unsigned) 
kbddata.char_ code): 
WriteSereen(ichar far *)6,5.,50) : 


sprintf(s,”Scan code: %02X”, (unsigned) 
kbddata.scan_code): 
WriteScreen((char far *)s.6,50): 


sprintf(s,”Status: %02X”, (unsigned) kbddata.status) ; 
welteSereen( (char far *)s.,7.,50): 


sprintf(s,”NLS Shift Status: %02X”, (unsigned) 
kbddata.nle shift) : 
WriteSereent(t (char far *)s,8,50)>: 


sprintfi(s,.”Shift State: %04X”, (unsigned) 
kbddata.shift state) : 
WriteScreen( (char far *)s,9,50): 


if (kbddata.char_code = 0 && kbddata.scan_code 
== K Q && 

( (kbddata.shift_state & (CNTRL | ALT)) == 
(CNTRL | ALT)) ) 

break; /* 

sprintf(s,”Time Stamp in milliseconds: %ld”, 
kbddata.time) ; 

WreiteSereen( (char far “)e,9,50); */ 


void cls() /* elear screen */ { 
char c[2]: 
e[O] = * *; #* eell to replicate is a blank */ 
c{1] = 7; /* with normal attributes */ 


/* elear gserean */ 
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VIOSCROLLUP(G, ©, <1, -1, -1, (ehar far *)ec, 0): 


void WriteScreen(s,x,y) 
char far *s: 
unsigned x,y; { 
VIGWRICHARSTR(s,strients), x,y, O); | 


yoid box(x,y,x1l,¥1) 
unsigned x,y,xl,yl; 


f statie char border[6] =—( “\eB3*.° \eC4’. > VeBr’,* eto". *\eDo’. 
‘.e DA? }: 


ant A: 
int row, column: 


VIOGETCURPOS (&row, &column,0O):; 


VIOWRTNCHAR (&border [HORZ] , (yl-y-1),x,yt+l,0); 
VIOWRTNCHAR (&border [HORZ] , (yl-y-1),xl,yt1,0); 


for (t=etl«i. < e)sarr) { 


VIOWRTNCHAR (&border [VERT] ,1,i,y,0) 
VIOWRTNCHAR (&border [VERT] ,1,i,y1,0) } 
VIOWRTNCHAR (&border[UPRT],1,x,yl1,0); 
VIOWRTNCHAR (&border[LWRT] ,1,xl,yl 0) 
VIOWRTNCHAR (&border [|UPLF] ,1,x,y,0) 
VIOWRTNCHAR (&border[LWLF],1,xl,y,0); 
VIOSETCURPOS (row, co Lum ,0) : /* move the cursor back */ 


f/* to oFiginal position */ } 


KbdStringin 


KbdStringIn reads a string of ASCII characters from the standard input device 
(STDIN). The function reads characters until the turn-around or end-of-line 
termination character is encountered. This is usually the carriage return 
(ASCII=13), but an alternate turn-around character can be specified with KbdSet- 


Status. 
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KbdStringIn accepts both 1-byte ASCII characters and extended (2-byte) ASCII 
characters, where the first byte is zero and the second byte will contain the 
extended code which is usually the scan code for the depressed key. Partial or 
incomplete codes for DBCS are not returned to the application either in raw or 
cooked mode. 

The function expects the following parameters: a pointer to the buffer where 
the character string is stored, a pointer to a memory block containing the specified 
request length and to a returned actual length for the string, the wait option, and 

keyboard handle. 
‘The variable Length specifies the pointer to the data structure containing both 
the length of the string which the program wishes to receive and to the actual 
length of the string returned by the function. The structure is a 4byte memory 
block containing two unsigned or word variables. The format of the structure is 
as follows: 


struct KbdStrInLength { 
unsigned InLength; 
unsigned OutLength; 


The parameter /nLength specifies the byte length of the buffer in which the 
program wishes to receive the input string. The maximum size of the string buffer 
that KbdStringIn can handle is 255 bytes. Parameter OutLength returns the length 
of the string in bytes that was actually read by the function. 

Variable JoWazt represents the wait option and indicates whether the function 
waits until a keystroke is entered or returns immediately if a keystroke sequence is 
not available. 


KbdStringIn (String, Length, |OWait KbdHandle) 


char far *String; /* string buffer pointer */ 
struct KbdStrInLength far *length; /* length structure pointer */ 


unsigned [OWait; /* wait option */ 
unsigned KbdHandle; /* keyboard handle */ 
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KbdFlushBuffer 


The function KbdFlushBuffer clears the keyboard input buffer. Any keystrokes 
that were inputted up to the time when the function is issued are erased. 


KbdFlushBuffer expects only one parameter, the default keyboard handle, or the 
keyboard handle returned by KbdOpen. 


KbdFlushBuffer (KbdHandle) 


unsigned KbdHandle; /* keyboard handle of buffer to be 
flushed */ 
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Keyboard Status 


Depending on the keyboard status, certain keystrokes are interpreted differ- 
ently. OS/2 has two input modes: raw mode and cooked mode (the terms are 
borrowed from structural anthropology, and denote the absence or presence of 
culture). In cooked mode certain key-stroke combinations send specific instruc- 
tions to the operating system with regard to the application accepting keyboard 
input. These special key-strokes and their effects are presented in the table below. 
In raw mode the ASCII code corresponding to these key-strokes is received, but 
OS/2 will not act on it. For example, suppose the keyboard is set to raw mode. 
Whenever a Cntrl-C is pressed, the application will receive the ASCII code 
representing Cntrl-C. But if the keyboard is in cooked mode when a CntrI-C is 
pressed, it is understood by OS/2 that the user wishes to terminate the execution 
of the program, just as if the user had pressed Cntrl-Break. (Cntrl-Break, however, 
is always interpreted as the program termination signal, even if the keyboard is in 
raw mode). 


Ctrl-S Toggle which pauses and continues the 
execution of the program currently 
accepting keyboard input. 


Ctrl-P Toggle which turns on and off the printer 
echo. 
Ctrl-C Generates a Ctrl-Break; a user request for 


the termination of the program currently 
accepting keyboard input. 


TAB Insert eight blank spaces onto the screen 
at the current cursor position. 


Table 14.1 Significant Cooked Mode Keystroke Combinations 
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The keyboard status includes all the information that characterizes the state of 
the keyboard. This includes whether the echo is on or off, the input mode is raw 
or cooked, the specified turn-around character, the state of the interim flag, and 
the shift states of the special keys on the keyboard. The echo mode determines 
whether the keystrokes are echoed on the video screen or not. The raw/cooked 
mode distinction was explained earlier. 

The turn-around character specifies the end of line termination character (the 
Return character is the default). The turn-around character is used by the function 
KbdStringIn, which reads a string of ASCII characters from the keyboard. When- 
ever OS/2 receives the ASCII code corresponding to the turn-around character 
(i.e. when the user has hit the turn-around character), OS/2 understands this to 
mean that the user has finished inputting the character string and the KbdStringIn 
function completes its execution. 

As explained earlier, the shift states of the keyboard change the translation of 
a keystroke’s scan code to an ASCII code. OS/2 allows an application to 
permanently set the shift states of the keyboard to a certain configuration. For 
example, an application can set the shift states so that every character entered will 
automatically have a shift state of left-shift down; causing all characters to automati- 
cally be input as uppercase (or lowercase if the Caps-Lock key is also down). 

During system initialization, OS/2 establishes the initial state of the keyboard 
as: echo mode, cooked mode, the Return key as the turn-around character, the 
interim flags not set, and no shift states set. An application can change the 
keyboard status to suit its own needs using the function KbdSetStaus. It can use 
KbdGetStatus to determine the current status of the keyboard. If an application 
changes the status of the keyboard with DosSetStatus, these changes only affect the 
status of the logical keyboard associated with the session in which the application 
is running. Keyboard buffers of other sessions are not affected. 


KbdGetStatus and KbdSetStatus 


OS/2 provides two functions for obtaining and setting the keyboard status, 
KbdGetStatus and KbdSetStatus. Both functions expect the same parameters: a 
pointer to a memory block containing the keyboard characteristics, and a key- 
board handle. When using these functions, the calling program must use the 
default keyboard handle (a zero). Other values for the keyboard handle are not 
allowed and will generate error # 439, “invalid keyboard handle.” The other 
parameter is a 10-byte data structure with the following format: 
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struct KbdStatus { 


unsigned Length; /* gize of the memory 
block */ 

unsigned BitMask; /* pit-mask values */ 

unsigned TurnAroundChar; /* ASCII code for turn 
around char */ 

unsigned Shiftstate: (* shift states of shift 


and toggle keys */ 


The parameter Length specifies the length of the memory block in bytes 
including the field Length itself. Function KbdSetStatus uses the BztMask parame- 
ter to make changes in the mode status of the keyboard. For KbdGetStatus, the 
BitMask parameter returns the current mode status of the keyboard. BztMask is a 
bit-mask value. The following identifies the significance of each bit in the variable: 
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The BitMask pattern contains several redundant pieces of information. Bits 0 
and 1 determine whether the keyboard is in echo mode or not (bit 0= on means 
echo mode is on, bit l= on means echo mode is off). Because of this they cannot 
both be 0 or set at the same time. If they are both set or 0 simultaneously when 
function KbdSetStatus is issued, an error will be returned. Similarly because 
separate bits are used to determine the raw/cooked status, both bits 2 and 3 cannot 
be 0 or set at the same time. One wonders why the designers of OS/2 didn’t just 
use one bit to represent status of each keyboard characteristic. 

Parameter turnaroundchar specifies the ASCII code of the turn-around charac- 
ter. The turn around character is used to determine the end of line of a character 
string for functions like KbdStringIn. Itis usually a carriage return (an ASCII value 
of 13). If the turn-around character is to be an extended ASCII code then bits 6 
and 7 of BitMask should be set. 

The interim flag is used for DBCS support as explained earlier. The parameter 
intermf lags indicates the interim character values. The value and meaning of each 
bit is: 
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The parameter ShifiStates represents the bit mask values for the status of the shift 
and toggle keys. For the function KbdSetStatus, the bit-mask values in this 
parameter are used to set the states of these keys. Whenever a keystroke is received, 
the shift states set by the application are automatically inserted into the data packet 
for each keystroke. If the shift state values are modified then the application 
receives each keystroke with the specified modified shift state. 

As explained, each session has its own logical keyboard buffer and the logical 
keyboard’s shift states are preset to certain values by OS/2 when the system is 
initialized. KbdSetStatus only affects the shift states of the logical keyboard in the 
screen group where it is issued. 

Shift states are usually stored in a 2-byte (WORD) or unsigned variable. The bit 
mask values of this variable represent the shift states of the shift keys and the status 
of the toggle keys that are in effect on the keyboard when another key is pressed. 
Recall that the status of shift and toggle keys determine the ASCII code that is 
generated when the scan code for a key is received from the keyboard. The 
following list identifies the meaning of each bit in the ShiftState variable that can 
be modified or determined using function KbdSetStatus and KbdGetStatus re- 
spectively'. The meaning listed represents the condition that is in effect when a 
bit in the bit-mask pattern is set (or equal to 1). Ifa bit is not set then the 
corresponding shift or toggle is not down or on. 





' Bits 8-15 represent the shift status of other keys. Currently, KbdSetStatus cannot change the shift state of these 
keys, and KbdGetStatus can only determine the shift states changeable by KbdSetStatus. Function KbdCharIn 
or KbdPeek can however determine the shift status of these other keys. 
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KbdGetStatus (KbdStatus, KbdHandle) 


KbdSetStatus (KbdStatus, KodHandle) 


struct CharData far *KbdStatus; /* pointer to keystroke information to be 
returned */ 
unsigned KbdHandle; /* pointer to keyboard handle */ 





Example 
f* RBEDSTR.C 


This program demonstrates how to use the functions: 
KbdStringIn, KbdGetStatus, and KbdSetStatus 


This program demonstrates how to use KbdStriIngIn to retrieve a 
string from the keyboard. OS/2 uses the turn around character as 
the termination character for the string. The default turnaround 
character is the carriage return <CR> or OxOD. 


596 Advanced Programmer's Guide to OS/2 


You can use DosSetStatus to change the turn around character to 
an ASCII code or an extended ASCII code. 


"7 


include “doscalls.h” 
include “subcalls.h” 


#fdefine LOBYTE(w) ((unsigned char) (w)) 
define HIBYTE(w) (( (unsigned) (w) >> 8) & Oxff) 


Htdefine ECHO_ON 0x0001 
Htdefine ECHO_OFF 0x0002 
4tdefine RAW_ON 0x0004 
4tdefine COOK_ON 0x0008 
Htdefine MOD_SSTATE 0x0010 
}tdefine MOD_INTERIM 0x0020 
4tdefine MOD _TURNACHAR 0x0040 
Htdefine TWO_BYTE 0x0080 
4tdefine SHIFT_ON 0x0100 


4Edefine MAX LENGTH 255 


#tdefine WAIT 0 
ffdefine NOWAIT 0 
#tdefine K_F1 0x003B /* £1 key */ 
main() { 
direct Kbdstatus kbdstatus: /* parameters for KbdGet 


Status. */ 
unsigned ret; 
char s [MAX LENGTH] ; 


struct KbdStringInLength strlength; 


kbdstatus.length = sizeof(struct KbdStatus); 


Keyboard Functions 597 


if (ret = KBDGETSTATUS (&kbdstatus, 0)) { 
printt(”’ \nKbdGetStatus failed: %d”,ret) ; 
POSEZIT (1, Gi): 

} 


orintt (* \nKeyboard statius:”): 

if ((kbdstatus.bit_mask & ECHO_ON)==ECHO_ON) 
prantft("\n. Echo moda ts on™) > 

if ((kbdstatus.bit_mask & ECHO _OFF)==ECHO_OFF) 
printf(”\n Echo mode is off”); 


if ((kbdstatus.bit_mask & RAW_ON)==RAW_ON) 
printf(”"\n Raw mode”): 


else 
orintt("\n Cook mode”) : 

if ((kbdstatus.bit_mask & TWO_BYTE) == TWO_BYTE) 
printf("\n Turnaround character is two-byte 
Lone.” )% 

else 


printf("’\n Turnaround character is one-byte 
lene. 7) 3 


printf(”"\n Turn around character: %02X : %02X”, 
HIBYTE (kbdstatus.turn_around_char), 
LOBYTE (kbdstatus.turn around char)) : 


/* calling KbdStringIn to get a string from keyboard */ 


printf(”’\n\nPlease enter a string: “); 

strlength.Length = MAX_LENGTH; 

if (ret = KBDSTRINGIN(s,&strlength,WAIT, 0)) { 
prantit(* \nKbdStringIin failed: “%d", ret) : 
DOSES ILL <0) s 

} 


erintel”’ \nStrine entered: “s",e) 
/* calling KbdSetStatus to change the turn around char to Fl */ 


kbdstatus.bit_ mask |= (MOD_TURNACHAR | TWO _BYTE); 
kbdstatus.turn_around_char = K Fl: 
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if (ret = KBEDSETSTATUS(S&kbdstatus, 0)) { 
prantt (*\nKbdGetStatus failed: “dA”, ret) : 
DOSEXIT (1,0) 


printf (*\n\nTurn around char is now Fi”); 


/* call KbdStringin again as a demonstration of the new 
turn around char */ 


prince (* \n\nPleasa aenter a string: “); 

strlength.Length = MAX _LENGTH; 

if (ret = KBDSTRINGIN(s,&strlength,WAIT, 0)) { 
erintE(* \nkodStringin failed: “d*.ret): 
DOSEXIT(T 0) 


printf(”’\nString entered: %s”,s); 


} 


Chapter 15 


Mouse API Functions 


the programming interface for the mouse is provided by a device subsystem 

called the mouse subsystem. This subsystem consists of two device drivers: the 
mouse driver proper, and the pointer draw device driver. The mouse driver 
handles the electrical signals sent from the mouse to the computer, and provides 
the device I/O control interface used by the Base Mouse Subsystem (BMS). 
OS/2 applications use the API functions supported by the BMS to manipulate the 
mouse. The pointer draw driver is only responsible for drawing the mouse pointer 
image on the screen. Itinterfaces closely with the mouse driver to determine where 
to draw the mouse pointer on the screen . 

Unlike the other device subsystems, the mouse subsystem has separate applica- 
tion interfaces for protected mode applications and for DOS compatibility mode. 
In protected mode, programs communicate with the mouse subsystem through a 
set of API functions that begin with the letters “MOU.” Mouse application support 
for DOS mode involves the use of interrupt 33H. The services provided by these 
two mouse interfaces are similar, but the syntax of the calls is very different. The 
protected mode subsystem is provided through a dynamic link library, while DOS 
mode uses an interrupt-driven interface. 

In this chapter, we explain the functions of both drivers and the types of support 
provided by the drivers for applications in both protected and DOS modes. We 
also discuss the configuration parameters for mouse drivers and other issues 
related to the operation of the mouse. 


| n the same way that OS/2 provides support for video display and the keyboard, 


Pointer Draw Screen Driver 


The pointer draw screen driver is responsible for displaying a mouse pointer on 
the screen at a position that corresponds to the current location of the physical 
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mouse. This task includes the representation of pointer movement according to 
the movement of the physical mouse. Mouse motion is determined by the draw 
screen driver through information sent to it by the mouse driver. The draw screen 
driver represents the motion of the mouse pointer by determining the mouse’s 
new position, erasing the image it drew at the mouse’s previous position, and then 
redrawing the pointer at the new position. This is done so fast that the user sees 
only the smooth movement of the mouse pointer across the screen. 

In protected mode, the pointer draw screen driver is only operational in text 
mode; the driver can then be switched to full-draw support mode. The pointer draw 
driver cannot operate in graphics or APA mode. It must be disabled before 
switching the mouse driver into graphics or disabled state mode. For applications that 
run in the DOS compatibility mode, the draw device driver can generate the mouse 
pointer in text mode as well as several graphics modes. 

Full-draw support mode is the default mode for an OS/2 screen group. 
Whenever the mouse interrupts the mouse driver in this mode, the mouse driver 
automatically calls on the pointer draw screen driver to refresh the mouse pointer 
image on the screen. Such support is provided for text modes 0, 1, 2, 3, and 7 for 
all adapters and displays supported by OS/2'. In full-draw support mode, the 
mouse pointer appears on the screen as a reverse video cursor. 

For protected mode applications, the pointer draw driver is not operable in 
graphics mode. In order for an application to use the mouse in any of the graphics 
modes, the pointer draw driver must be disconnected by switching it to the 
disabled state mode. The application, itself, must monitor the movement of the 
mouse and draw the mouse pointer at the correct position on the screen. This 
allows an application to substitute a different image for the mouse pointer. With 
the pointer driver in disabled state, an application can manipulate the mouse in 
any of the above mentioned text modes and in the following graphics modes: 

4 5,6, 7, Dy. B, F, 10,11, 12, and 13. 

For systems installed with the IBM PS/2 8514A display adapter, the advanced 
graphics modes of the adapter are also supported. 

The function MouseSetDevStatus is used to switch between full-draw support 
and disabled state support. Just before changing from the disabled state to the full- 
draw state, the current mode of the video adapter must be set to one of the text 
modes supported by the full-draw state using the function VioSetMode. Switching 
to disabled state mode is always possible, even when the display mode is in text 
mode. Before an application can switch to any of the graphics modes, it must first 
switch the pointer screen driver to the disabled state, otherwise the pointer draw 
driver will unsuccessfully attempt to draw a mouse pointer image. The resulting 


'Please refer to Chapter 13 for a detailed discussion of the possible graphics and text modes. 
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error will shutdown the mouse driver. In case of a shutdown, the mouse driver no 
longer sends data to the Base Mouse Subsystem. ‘The application can still use API 
functions provided by the BMS, but no data will be returned (1.e., nothing will 
happen). An application can use the function MouGetDevsStatus to determine 
whether the mouse driver is active or not. 


Mouse Drivers Parameters for Config.Sys 


Which mouse driver is installed in the config.sys file depends on the type of 
mouse being used and the type of system on which it is being installed (PC or 
PS/2). A list of the driver names and the mouse supported by each is provided on 
page 641. A mouse driver is specified in the config.sys file in the following format: 


device =<driver name> |, parameters] 


The driver name can include the path and drive where the device driver is 
located. The optional parameters after the driver name consist of three keywords: 
serial=, gsize=, and mode=. Each keyword must be separated by a comma (,). 

The keyword serial= <communication port number> is used for serial mouse devices 
to specify the communication port number to which the mouse is attached. For 
AT-type computers, there are only two ports: COM1 and COM2. PS/2 machines 
support eight communications ports: COM1 through COM8. This keyword 
cannot be used with a bus or non-serial mouse (e.g., the Microsoft Bus Mouse, IBM 
PS/2 In-Processor Mouse and Microsoft InPort Mouse). If this keyword is not 
specified, the default for serial a mouse is COM1. 

The keyword qsize = <integer> specifies the maximum number of events that can 
be placed in the queue maintained by the mouse driver to store data generated by 
the mouse. The value must fall within the range from 1 to 100. The default value 
is 10. Each event requires 10 bytes of storage. A value of 20 events requires 200 bytes 
of buffer space to be maintained by the mouse driver. 

The keyword mode = <character> specified the type of mode the mouse driver 
will support. The possible values for the character are as follows: 


B - Support both OS/2 protected and DOS compatibility 
modes 

P - Support only the protected mode 

R - Support only the DOS compatibility mode. 


The default for the mouse driver is to support both modes. 
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The following lines install a mouse driver for COM2, with a maximum of 50 
elements. Both protected and compatibility modes are supported. 


device = MOUSHEAO]L.SY¥S, sérial = COMZ, MODE —~ B., GsIZE = 50 


Mouse Operations 


This section serves as an introduction for those who are not familiar with the 
issues involved in mouse operations. A mouse is a pointing device that is usually 
used in conjunction with the keyboard to provide a friendly user interface. The 
mouse is usually used to perform such operations as choosing an item from a 
menu, defining a screen area, or drawing figures and lines. In other words the 
mouse is used to input information into the system which is most intuitively 
represented graphically. The use of the mouse is tightly coupled to the video 
screen. Movement of the physical mouse across a surface causes a corresponding 
movement of the mouse pointer on the video screen. For this purpose, a grid is 
mapped onto the screen, and the physical mouse lies on a corresponding 
imaginary grid. User input from the mouse varies with the location of the mouse 
pointer on this grid. For this reason the manipulation of a mouse by a program 
involves more than just receiving data. Mouse manipulation includes certain 
screen related issues: the shape of the mouse pointer, the correlation between the 
physical movement of the physical mouse and number of picture elements (pels) 
traversed by the mouse pointer, and the definition of areas on the screen from 
which the mouse pointer is restricted. 


Events 


The mouse is a simple input device, or a read-only device, which can send data 
at arate of 30 events per second. Each physical mouse operation is considered an 
event which is signalled to the mouse driver as a hardware interrupt. The mouse 
can only generate a few types of events: movement of the mouse, the depression 
or release of the mouse buttons, or a combination of both. The following is a list 
of events that can be generated by a mouse: 

#" Motion without any button pressed 


# A button is pressed 
# A button is released 


= A button is pressed with motion 
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The mouse device subsystem maintains the following information for each 
mouse event: the type of event, a time stamp (in milliseconds), and the current row 
and column position of the mouse. If the mouse has not been moved, its column 
and row coordinates are the same as those for the last event. Any mouse movement 
can be represented as a change in its coordinates over time. By monitoring all the 
coordinate displacements of the mouse within a period of time, we can determine 
the extent of its motion. 

The double-click of a mouse button is often used to signify a special sort of event. 
For example, it often signifies that the user has made a choice from a pull-down 
menu. We can determine whether a double-click of the mouse button has 
occurred by monitoring the timestamps maintained for mouse events. If the 
sequence “button pressed, released, pressed again, released again” occurs within 
a specified number of milliseconds, then the user has double-clicked the mouse 
button. The time-interval that specifies a double-click is a variable which can be set 
for each application. 


Scale Factor 


The essence of a good mouse interface lies in the relationship between the 
distance the physical mouse is moved and the corresponding distance travelled by 
the mouse pointer. The mouse interface’s sensitivity to movements made by the 
physical mouse is adjustable (a certain displacement of the physical mouse can 
correspond to a greater or lesser displacement of the mouse pointer) depending 
on the task at hand. For example, a drawing program needs to be much more 
sensitive to mouse movements than a text-editing program. OS/2 provides 
functions to adjust the mouse sensitivity. 

In full-draw support mode, changing the sensitivity of the mouse directly 
changes how far the mouse pointer 1s displaced when the physical mouse is moved. 
In disabled mode, the application must draw the mouse pointer itself, however the 
mouse driver does track the mouse’s position and reports it to the application. This 
position can be thought of as the virtual mouse pointer. The application merely 
has to draw the mouse pointer at this position. 

The sensitivity of the mouse is adjusted by varying the ratio between the number 
of units the physical mouse moves and the number of units the mouse pointer or 
virtual mouse pointer moves on the screen. This ratio is called the scale factor for 
the mouse. 

The smallest unit of movement that is recognized by a physical mouse is called 
a mickey. ‘The motion of the mouse pointer in text mode is measured in rows and 
columns of characters. The motion of the virtual mouse pointer in graphics mode 
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is measured in pixels (pels). In character mode, the default relationship between 
the physical mouse and the mouse pointer causes the pointer to move | character 
(1 column) horizontally for every eight mickeys of horizontal mouse motion, and 
1 row of characters vertically for every 16 mickeys of vertical mouse motion. In 
graphics mode, the default relationship is 8 pels of horizontal virtual pointer 
displacement for 8 mickeys of horizontal mouse movement, and 8 pels of vertical 
virtual pointer displacement for 16 mickeys of physical mouse movement. If we 
assume a text mode character size of 8 x 8 pels, then we see that both default scale 
factors result in the same amount of pointer movement per physical mouse 
movement in both full-draw support and disabled modes. The difference, of 
course, being that in disabled mode the application must draw the mouse pointer 
itself. 

The default ratio between mickeys and pixels in full-draw support mode can be 
determined and changed using the functions MouSetScaleFact and MouGetScale- 
Fact. Changing this ratio changes the sensitivity of the mouse pointer to the 
movement of the mouse. This information is provided in the form of number of 
mickeys per row and column. For example, if we define a ratio of 50 mickeys per 
8 columns, and 100 mickeys per row, the physical mouse will have to be moved a 
long distance before the mouse pointer moves on the screen. 

Each mouse driver maps a limited physical area (desk space) corresponding to 
the sensitivity of the installed mouse and the ratio between number of mickeys 
moved and the corresponding movement in pixels of the mouse pointer. For 
example, using the default mickey/pixel ratio, the Microsoft bus mouse must be 
moved 6.4 inches horizontally and 4.0 inches vertically in order for the mouse 
pointer to traverse the video screen from corner to corner. The PS/2 mouse is 
more responsive and requires a movement of only 3.2 inches horizontally, and 2.0 
inches vertically in order for the mouse pointer to traverse the screen diagonally. 
An application can determine the ratio between the number of mickeys per screen 
displacement (horizontal and vertical) in centimeters using the function 
MouGetNumMickeys. This ratio is determined using the scale factor discussed in 
the previous paragraph. 


Shape of Mouse Pointer 


In text mode, the mouse pointer is simply a reverse video cursor block. This 
represents a character sized block, which is all that is needed in text mode. In 
graphics mode, the application is responsible for displaying the mouse pointer, 
and can specify its own mouse pointer image. The function MousSetPtrShape 
allows an application to create a mouse pointer image. This image is specified by 
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a bitmap, which can be returned to an application using the function 
MousGetPtrShape. For real mode applications the pointer draw driver creates a 
reverse video cursor block in both text and graphics modes. Real mode applica- 
tions can use the INT 33H function 9 to change the shape of the mouse pointer. 


Collision Area 


A collision area is a section of the screen grid which the mouse pointer cannot 
enter. The specification of a collision area can be used to make the user aware of 
the bounds of his or her workspace, or of a function that is currently unavailable 
for use. The function MousRemovefPtr is used by OS/2 text-mode applications in 
full-text support mode to inform the pointer draw driver of an area of the screen 
grid which it wishes to declare as collision area. The function MouDrawPtr clears 
all restricted areas from the screen and allows the mouse pointer free access to the 
entire screen grid. Neither of these functions are used by graphics mode 
applications. Graphics mode applications are responsible for managing their own 
collision areas. 


Mouse Operation Functions 


Before an application can receive data from or otherwise manipulate a mouse, 
a mouse handle must be obtained using the function MouOpen. All subsequent 
mouse functions require the mouse handle. The mouse handle is like any other 
device or file handle; once the mouse is no longer needed by the application, the 
mouse handle must be closed using the function MouClose. A mouse handle is 
supplied to each process that issues the MouOpen call. However, the BMS can only 
handle the synchronization needed to share one physical mouse among several 
sessions (or screen groups) with the help of the Session Manager. It cannot 
synchronize access to the mouse among multiple processes within the same screen 
group. Ifthe mouse is to be shared among several processes within the same screen 
group, the sharing of the mouse amongst them can be thought of as being akin to 
the problem of sharing any other SRR. The synchronization needed to do this 
must be handled by the session itself, and not by OS/2. OS/2 does, however, 
provide a facility that allows an application to intercept all MOUxxx calls in order 
to synchronize access to the mouse among several processes within the same screen 
group. This facility is also used by the Presentation Manager to allow several 
applications to operate within the same screen group. It is discussed in Chapter 17 

In order to access the mouse, an application must be running in the fore- 
ground. If any thread in a background session attempts to access the mouse, it is 
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halted by the Session Manager. This background session thread’s execution will 
only be resumed when it is switched to the foreground. 

Each mouse handle is unique to a single session. Unless the application wishes 
to intercept MOUxxx calls and do the access coordination itself, there should be 
only one process per session that has access to the mouse handle. This means that 
only one process per application or session can issue MouOpen and MouClose. 

Once the mouse is opened, the mouse driver initializes the state of the mouse 
handle. The mouse handle state is specific to the session that currently has access 
to the handle and changes in the state are only applicable to that particular session. 
The mouse handle states of other sessions are not affected. 


The initial states of the mouse are: 


Feature Initial State 


Events All type of events are registered (this can be 
changed later using MouSetEventMask). The 
event queue is empty. 


Scale Factor 16-row pixels equals 8 horizontal mickey units. 
8-column pixels equal 8 horizontal mickey units. 


Pointer Draw Mode The pointer draw driver is set to full-draw support 
mode. The function MouSetDevStatus can be 
used to change the mode to disabled-state sup- 
port mode. 


Collision Area The entire screen is defined as the collision area. 
No mouse pointer is displayed in the initial state. 
To display the mouse pointer use the functions 
MouDrawPtr or MouRemovePtr to define a new 
collision area. 


Pointer Position The mouse pointer is set to the middle of the 
screen. Function MouSetPrtPos can be used to 
change the mouse pointer position on the 
screen. 


Pointer Shape Pointer shape is set to the current default pointer 
shape provided by the mouse driver. 


Movement Units The movement unit is predefined to be relative 
to an absolute coordinate which is the top row 
and leftmost column, or 0,0. In text mode, the 
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movement unit is in column and row numbers, 
and in graphics mode, in pixel numbers. The 
movement unit can be changed to mickey units 
using MouSetDevStatus. 


There are several important consequences that follow from the initial state of 
the mouse which should be noted by the programmer. The pointer draw driver 
is originally set to full-draw support mode. In order to manipulate the mouse, the 
video mode for the application must be set to one of the text modes supported by 
full-draw mode. Otherwise the BMS will not be able to access the mouse driver 
(because the mouse driver will be disabled by an error sent to it by the pointer draw 
driver). For graphics-based applications, once the mouse has been opened in text 
mode the state of the mouse can be switched to the disabled state, and the video 
mode switched to one of the graphics modes. In addition, when the mouse is first 
opened the entire screen is defined as a collision area. No pointer is displayed until 
the application uses the function MousDrawPtr to clear the collision area, or the 
function MouRemovePtr to change the size of the collision area. 

Another default setting is the unit which is used to measure mouse motion. The 
default is to represent the motion of the mouse as a series of coordinates which vary 
over time. In this case each coordinate reported for the mouse is accompanied by 
atime stamp. The other possible method is to represents mouse motion in relative 
terms, as a displacement, in mickeys, from a previous position. A negative value of 
n for the the row position represents a movement of the mouse n mickeys toward 
the top of the screen from the previous position. Similarly a positive value of n for 
the column position of the mouse represents a mouse displacement of m mickeys 
to the right of its previous position. The function MouSetDevStatus is used to 
define which method of motion measurement is used by the device driver. 


Manipulation of the Mouse in Disabled State Mode 


When the pointer draw driver is switched to the disabled-state mode the 
application becomes responsible for drawing the mouse pointer as well as keeping 
track of mouse motion. The following describes the steps necessary to draw the 
mouse pointer in the disabled state: 

1. Use MouSetDevStatus to switch the mouse draw driver to switch from full- 

draw to disabled state mode. No pointer will be displayed at the completion 
of this call. 


2. Use VioSetMode to change the mode of the video adapter. 


3. Define the mouse pointer shape using function MouSetPtrShape. 
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4. Continuously monitor the change in the mouse position using the function 
MouReadEventQueue? 


5. Move the mouse pointer to the correct screen coordinate with function 
MouSetPtrPos, and draw the mouse pointer. 


MouOpen and MouClose 


MouOpen opens the mouse and returns the access handle to the calling 
application. ‘Two parameters are required: a pointer to a two-byte memory block 
where the handle will be returned by OS/2, and the address of a memory block 
containing the name of the pointer draw driver. The name of the driver must be 
the same as the name included in the config.sys file. For applications that want to 
use the default pointer draw driver provided by OS/2, the address should be set 
to null (for C programs, this is OL or a double word of zeros [0s]). This facility 
allows an application to specify its own pointer draw device driver to support a 
mouse device not supported by OS/2, or to specify a driver that provides greater 
functionality than the default pointer draw driver. 

The function MouOpen also sets the mouse handle to the default state 
described above. Other mouse functions should be used to change the mouse 
handle state to meet the needs of the application. 


MouOpen (DriverName, MouHandle) 


char far *DriverName; /* name of the pointer draw device 
driver */ 
unsigned far *MouHandle; /* pointer to the mouse handle to be 


returned */ 





?This is the major difference between operating the mouse in disabled mode rather than in full draw support 
mode. In full draw support mode the application does not have to act on every mouse event, only those with 
significance (such as choosing a menu). In disabled mode the application must act on every event in order to 
redraw the mouse pointer. 
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Function MouClose terminates access to the mouse handle for the calling 
session. Further access to the mouse within the session with other MOUxxx 
functions will meet with an error unless MouOpen is issued again. MouClose 
deletes the mouse handle from the current list of valid mouse handles maintained 
by the mouse device driver. MouOpen adds a new handle to the list. 


MouClose (MouHandle) 


unsigned MouHandle; /* the mouse handle to be removed */ 





Event Functions 


Every time the mouse moves or a mouse button is pressed or released, the 
occurrence of an event is signalled to the mouse device driver. Each event is stored 
in a circular FIFO (First-In-First-Out) queue maintained by the mouse driver for 
each screen group. No matter how many process currently share the mouse within 
a screen group, there is still only one queue per session. Mouse events are 
represented on the queue as data elements. These are placed on the queue in 
order of occurrence. When the queue is full, the driver puts the next event at the 
beginning of the queue, overwriting the previous first element. The size of the 
queue is determined by the configuration parameter in config.sys (see page 601). 
The function MouGetNumQueE] reports the number of elements currently on 
the queue. The function MouReadEventQue retrieves the first event element 
from the head of the queue. The function MouFlushQue can be used to clear the 
event queue of all elements. 

An OS/2 application can also be selective about which sort of events it wishes 
to receive from the mouse. The function MouSetEventMask can be used to set up 
an event mask which instructs the device driver to place certain types of events on 
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the event queue and to ignore others. An application can determine the current 
status of the event mask using the function MouGetEventMask. 

The mouse is primarily used as an input tool which works by pointing to areas 
on the screen. The best way to understand its use is to discuss concrete input 
operations such as selecting a menu or defining a screen area. To select a menu, 
the user moves the mouse to the area on the screen where the menu is located, then 
clicks or double-clicks the mouse button, depending on the type of menu. To 
define a specific screen area, the mouse is placed at a point on the screen that will 
serve as an anchor point, the mouse button is depressed, and the mouse is moved 
to the other corner of the screen area to be defined while the button is held down. 
An alternate way in which the mouse is sometimes used to define a screen area is 
to double-click the mouse at the anchor point, move the mouse to the other corner 
of the screen area to be defined, and then click again. 

MouReadEventQue returns a data structure for each mouse event which 
contains the following information: the type of event, the time-stamp of the event, 
and the current position of the mouse. The type of event specifies whether the 
mouse has been moved and/or whether any button has been pressed. The 
mouse’s position can be returned in absolute or relative coordinates. Absolute 
coordinates return the current position of the mouse asa rowand column number. 
In this case, the motion of the mouse is calculated by comparing the current row 
and column position with a previous one. Relative coordinates return the mouse’s 
current position as a displacement, in mickeys, from the previous one. 

The following pseudocode illustrates how the mouse would be used to receive 
a user’s menu selection. (Please note that the pseudo-code is not concerned with 
drawing the mouse pointer image or the defined area). 


define menu area (top_row, bottom_row, left_column, 
right_column) 
clear the event queue 


press = NO; 


WHILE selection <> QUIT 
BEGIN 
MouReadEventQue (type_of_event, time_stamp, 
row number, col number) 
/*check whether the mouse is in 
the menu area */ 
IF (top_row <= row_number <= bottom_row) AND 
(left_column <= col_number <= right_column) THEN 
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IF (type_of_event is a button pressed) 
press = YES 
ENDIF 
IF (type_of_event is a button released) AND (press = 
YES) 
User has selected the menu 
ENDIF 
END 
ENDIF 
END WHILE 


The following pseudo-code illustrates how to detect screen area definition. 
clear the event queue 


press = NO 
motion = NO 


anchor row=0 
anchor col=0 


WHILE selection <> QUIT 
BEGIN 
MouReadEventQue (type_of_event, time_stamp, 
row_number,col_number) 


/* detect the anchoring */ 
IF (type_of_event is a button pressed) AND (press = NO) THEN 
press = YES 
anchor_row = row_number 
anchor_col =col_number 
ENDIF 
/* detect motion and pressed- 
button */ 
IF (type_of_event is a button pressed) AND (press = 
YES) AND 
(anchor_row <> row_number OR anchor_col <> 
col_number) 
THEN 
MOTION = YES 
ENDIF 
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/* user just release the button without motion*/ 
IF (type_of_event is a button released) AND 
(anchor_row = row_number) 
AND (anchor_col = col_number) AND (press = 
YES) 
THEN 
press =NO 
ENDIF 


J* detract the other corner by the release of 
the mouse */ 
IF (type_of_event is a button released) AND (motion 
= YES) THEN 
area is selected (anchor_row, anchor_col, 
row _number, col_number) 
ENDIF 


END WHILE 


MouSetEventMiask And MouGetEventMask 


The function MouSetEventMask is used to set up an event mask which causes 
the mouse driver to filter certain types of events. These events are not placed on 
the event queue. An event mask is specific to a particular mouse handle. Mouse 
handles for other sessions are not affected by this call. 

The functions MouSetEventMask and MouGetEventMask require the same two 
parameters: the mouse handle, and a pointer to a 2-byte memory block containing 
the event mask. For function MouSetEventMask, the memory block must be filled 
with the event mask to be set, for function MouGetEventMask, the current event 
mask is returned to this memory block. 


MouSetEventMask (EventMask, MouHandle) 
MouGetEventMask (EventMask, MouHandle) 


unsigned far *EventMask; /* pointer to the event mask */ 


unsigned MouHandle; /* mouse handle returned by 
MouOpen */ 
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For EventMask, if a bit is off (set to 0), then the event(s) associated with that bit 
will not be placed on the event queue. If bits 0-6 are set (to 1), all events will be 


received. The mouse buttons 1 and 2 refer to the left and right mouse buttons, 
respectively. 
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MouGetNumQueEl 


A mouse driver can handle only a certain maximum number of elements on 
each of its event queues. This parameter is specified in the config.sys file along with 
the mouse driver. The function MouGetNumQueEl informs an application of the 
number of event elements currently on its event queue, as well as the maximum 
number of elements that are allowable for its queue (in other words, the size of its 
queue). 

The function MouGetNumQueE]l expects two parameters, a pointer to the 
queue data record and the mouse handle. The queue data record is a 2-word (4 
byte) data structure which contains the number of elements on the event queue 
and the maximum number of elements for the queue. The data structure has the 
following format: 


strict QuelInfo { 


unsigned Events; /* current number of elements on 
queue */ 
unsigned QSize; /* maximum number of queue 


elements */ 


MouGetNumQueEl (QueDataRecord, MouHandle) 


struct QuelInfo far *QueDataRecord /* a two-word block containing the 
current and maximum number of 
elements */ 


unsigned MouHandle; /* mouse handle to be queried */ 
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MouReadEventQue 


The function MouReadEventQueue is used by an application to read the mouse 
event at the head of the event queue (the event is then removed from the queue). 
The function returns a data structure which fully describes the mouse event for the 
application. This structure contains the type of event, a time-stamp for the event, 
and the current absolute/relative row and column coordinates depending on the 
current status of the mouse handle. 

When absolute coordinates are requested by the application, the mouse driver 
returns a row and column number representing the current mouse position. In 
text mode this value is in rows and columns of characters (for most text displays the 
screen size is 40 x 80). In graphics mode, these row and column numbers are in 
actual pels (an EGA board and display supports a screen size of 350 x 640 pels). In 
either case a value of 0,0 indicates the top left-most corner of the screen. A location 
specification of 20 x 40 in text mode, or 175 x 320 in graphics mode, specifies the 
center of the screen. 

When the mouse position is requested in relative units, the mouse driver returns 
mickey units that represent the change in the mouse’s position as compared to the 
previous event on the queue. A negative mickey value signifies that the mouse has 
been moved to the left a certain number of rows, or up a certain number of 
columns. A positive mickey value means the reverse. When using relative units the 
application must calculate the relationship between mickeys moved by the mouse 
and the displacement of the mouse pointer on the screen itself. 

MouReadEventQue expects three parameters: a pointer to the event data 
structure, the wait option, and the mouse handle. The wait option specifies 
whether the calling process will wait for an event if the queue is empty. If there are 
no events and the no wait option is specified, a null event data structure is returned. 
The wait option is specified by the variable WaztOption. The possible values for 
WaitOption are as follows: 
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The format of the event data structure is as follows: 
struct EventInfo { 


unsigned Mask; /* type of event */ 

long Time; /* time-stamp */ 

unsigned row; /* absolute/relative row value */ 
unsigned col; /* absolute/relative column value */ 


} 


The field Time represents the time of day in milliseconds. The fields Row and 
Colrepresent the current coordinates of the mouse. If absolute mode is specified, 
the driver returns the coordinates as row and column numbers for video text mode 
and as pixel numbers for the graphics mode. Ifrelative mode is specified, the unit 
mickey is used. 

The field Mask represents the type of event or the state of the mouse at the time 
specified by Time. The field is a bit-mask value with the following bit values: 
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The event mask set bit MouSetEventMask only determines which types of events 
should or should not be placed on the event queue. Once an event is placed on 
the queue, the entire status of the mouse is returned including events which the 
event mask has specified to ignore. 

In our first example there will be no discrepancy between the values screened 
for with eventmask, and those that appear in the event queue. Ifan application was 
only interested in events generated by button 2, it would set bits 3 and 4 of the 
EventMask. If button | is depressed and/or the mouse is moved, then no event is 
generated. If button 2 is pressed, then an event is placed on the queue with bit 4 
of EventMask set. If the mouse is also in motion when button 2 is pressed, then bit 
3 of EventMaskis also set. Once the mouse stops moving and button two is released, 
all EventMask bits are off. 

In our second example, the returned EventMask has a value that was supposed 
to be screened by the EventMask. Assume that we have the same EventMaskas above. 
If button | is pressed, no event is generated. If button | is pressed with motion, no 
event is generated either. Butif button 2 is pressed along with button 1, bits 2 and 
4 are set even though the EventMask is supposed to ignore bit 2 events. The 
EventMask is used to screen events that do not have the qualities that the 
application is waiting for (for example, events which did not include button 2 
being pressed), it cannot prevent additional event characteristics from appearing 
on the queue (the fact that the EventMask variable reports that button 1 was 
depressed, even though this event was screened for). 


MouReadEventQue (Buffer, WaitOption, MouHandle) 
struct EventInfo far *Buffer; /* event data structure */ 
unsigned WaitOption; /* wait/no-wait option */ 


unsigned MouHandle; /* mouse handle */ 
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MouFlushQue 


MouFlushQue empties the event queue maintained by the mouse driver for the 
current session. MouFlushQue does not affect the event queue of any other 
session. 


MouFlushQue (MouHandle) 


unsigned MouHandle; /* mouse handle */ 





Example 


/* MOUSE.C 


This program demonstrates how to use the following mouse functions: 





MouOpen 
MouSetPtrPos 
MouRemovePtr 
MouGetEventMask 
MouSetEventMask 
MouReadEventQueue 
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The program sets up acollision area defined by a box on the screen, 
then displays all queue events, button presses, and the current mouse coordi- 
nates. To exit the program, the user needs to press the mouse button 2 


“7 


4tinclude <doscall.h> 


4#tdefine MOTION 0x0001 F? 
/t}define BUTTON1_ MOTION 0x0002 /* 
f}define BUTTON1 0Ox0004 j* 
+#define BUTTON2 MOTION 0x0008 /* 
4tdefine BUTTON2 0x0010 

4tKdefine BUTTON3_MOTION 0x0020 /* 
}tdefine BUTTON3 0x0040 

#tdefine WAIT 1 jf 
#tdefine NOWAIT 0 

+#define VERT 0 th 
4Hdefine HORZ 1 

ftdefine UPRT z 

ttdefine LWLF 3 

ttdefine LWRT dy 

4tdefine UPLF S 


yoid box (xi7sx1,71) 
unsigned x,y,xl,yl1; 


static char border [6] ={ ‘\xB3’,’\xC4', 


‘\xDA’}; 


tHt i: 


constants for EventMask */ 
receive button 1 and motion */ 
receive only button 1 events*/ 
button 2 values */ 


button 3 values */ 


for MouReadEventQueue */ 


definition for drawing box */ 


"\BE, “CO! , De, 
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int tow, column: 
VIOGETCURPOS (&row, &column,0O); 


VIOWRTNCHAR (&border [HORZ] , (yl-y-1),x,ytl,0); 
VIOWRTNCHAR (&border [HORZ], (yl-y-1),x1l,yt1,0); 


for (4=ef1lei < xleattt) { 
VIOWRTNCHAR (&border [VERT] ,1,3 
VIOWRTNCHAR (&border [VERT] ,1 


VIOWRTNCHAR (&border 
VIOWRTNCHAR (&border 
VIOWRTNCHAR (&border 
VIOWRTNCHAR (&border 


VIOSETCURPOS (row,column,0O); /* move the cursor back */ 
/* ~6 oviginal position */ 


void cls() /* clear sereen */ 


char cl2|: 


c[O] =‘ ¢‘; /* eel] to faplicate 16 a blank */ 
c{l] = 7; J* with nermal attributes */ 


(* elear screen */ 
VOOSGROLLUP(O, G, <1, -1, <1, (char far *}e, 6); 


void WriteScreen(s,x,y) 
char *s: 
unsigned x,y; 


{ 


main() 


VIOWRTCHARSTR(s.strlen(s), x,y, 0); 
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unsigned MouHandle; /* parameter for MouOpen */ 
struct PrrLoc PtrPaa: /* parameter for MouSetPtrPos */ 
struct NoPointer PtrArea;/* for MouRemovePtr */ 


unsigned EventMask; /* for MouSetEventMask and 
MouGetEventMask */ 


struct EventInfo MouPos; /* for MouReadEventQueue */ 
unsigned read_type; 


char s[80]; 


unsiened x,y, Kl,y1; 
unsigned ret, done; 


elei)s 

x=5; /* the collistion area coordinates */ 

y = 10; /* will be the area in the box */ 
xl= 10% 

yim 303 


box(x, ¥, eLyyl): 
WriteScreen(“Collision Area”,6,12): 
WriteScreen(“MOUSE STATUS”, 3,40); 


WriteScreen(“Current Mouse Position: “, 5,42): 

WriteScreen(“Click Button 2 to exit program” ,3, 0); 

if (ret = MOUOPEN((char far *)0, (unsigned far *) 
&MouHandle)) { 


printf (*\nMoulpen failed %d”,ret) : 
DOSEXIT(1,0); 
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PtrPos.RowPos = 10; /* get pointer position */ 
PErros.VolPos 20; 


if (ret = MOUSETPTRPOS((struct PtrLoc far *)&PtrPos, 
MouHandle)) { 
printf (“\nMouSetPtrPos failed %d”,ret); 
DOSHAIT( 1,0) % 


PerAreas ,kow = x; 
PtrArea.Col=y; 
PtrArea.Height=x1; 
PtrArea.Width=yl; 


if (ret =MOUREMOVEPTR( (struct NoPointer far *)&PtrArea, 
MouHandle)) { 
printf (“\nMouRemovePtr failed: %d”,ret); 
DOSEXIT(I, OL: 


if (ret = MOUGETEVENTMASK( (unsigned far *)&EventMask, 
MouHandle)) { 
printf (“\nMouGetEventMask failed: %d”,ret):; 
DOSEXIT (1,0); 


sprintf(s,”Default Event Mask: %d “ EventMask) ; 
WriteScreen(s,/7,42); 


EventMask=MOTION| BUTTON1_MOTION | BUTTON2_MOTION | 
BUTTON1 | BUTTON2; 


if (ret = MOUSETEVENTMASK((unsigned far *)&EventMask, 
MouHandle)) { 


printf(“\nMouSetEventMask failed: %d”,ret); 
DOSEXIT(1,0) ; 


read_type = WAIT; 
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while (1) { 


ret = MOUREADEVENTQUE( (struct EventInfo far *) &MouPos, 
(unsigned far *)&read_type, 
MouHandle): 


tf (ret) | 
printf (“\nMouReadEventQueue Failed: %d”, ret); 
DOSEXIT(1,0) ; 

} 


if (MouPos.Mask == MOTION) { 
sprintf(s,”%02d %02d” ,MouPos.Row, MouPos.Col); 
WriteScreen(s,5,67); 
WriteScreen (“ * 6,42): 

} 


if (MouPos.Mask == BUTTON1_MOTION | | 
MouPos.Mask == BUTTON1) { 
sprintf(s,”%02d %02d” ,MouPos.Row, MouPos.Col); 
WriteScreen(s,5,67); 
WriteScreen(“Buttonl was pressed” ,6,42); 


if (MouPos.Mask == BUTTON2 | | 
MouPos.Mask == BUTTON2_MOTION) { 
break; 


Scaling Functions: MouGetScaleFact, MouSetScaleFact and 
MouGetNumMickeys 


The scaling factor is the conversion ratio between units of physical mouse 
movement (mickeys) and the movement of the mouse pointer (in full-draw 
support mode), or the virtual mouse pointer (in disabled mode). Two functions 
are used to determine or set the scaling factor, MouGetScaleFact and MouSet- 
ScaleFact. Please refer to page 603 for a detailed discussion of the issues involved. 
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Both functions expect the same parameters: the mouse handle, and a pointer 
to a memory block where the scaling values are returned in the case of MouGet- 
ScaleFact, or to be used to change the scale factors for function MouSetScaleFact. 
The memory block is a 4byte data structure containing two unsigned or WORD 
variables. 


struct ScaleFact { 
unsigned RowScale; i/* geale factor for tow */ 
unsigned ColScale; /* sonle taeror for column */ 


In full-draw support mode (text mode), the scale factor is specified in mickeys 
per row and column of characters. In disabled mode it is specified in mickeys per 
row and column of pels. The default scale factor in full draw support mode is 8 
mickeys per 1 column horizontal, and 16 mickeys for 1 vertical row. In disabled 
mode this translates into 8 mickeys per 8 pixels horizontal, and 8 mickeys per 16 
pixels vertical. RowScale specifies the row scale factor and ColScale specifies the 
column. The values for these variables must fall within the range 0 to 32767. 


MouGetScaleFact (Scale, MouHandle) 


MouSetScaleFact (Scale, MouHandle) 


struct ScaleFact far *Scale; /* pointer to scale factor structure */ 


unsigned MouHandle; /* mouse handle */ 
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The function MouGetNumMickeys returns the conversion ratio between the 
number of mickeys per centimeter for the actual height and width of the screen. 
This ratio is dependent upon the current scale factor. MouGetNumMickeys 
expects two parameters: the mouse handle, and a pointer to a two-byte or WORD 
variable where the ratio is be returned. The values returned will be within the 
range from 0 to 32767. 


MouGetNumMickeys (NumberOfMickeys, MouHandle) 


unsigned far *NumberOfMickeys; /* pointer to scale factor structure */ 


unsigned MouHandle; /* mouse handle */ 





Pointer Shape 


The shape of the pointer representing the mouse on the screen is defined and 
returned using MouSetPrtShape and MouSetPtrShape. There are two types of 
pointer shapes: one for text mode and the other for graphics mode. The text mode 
mouse pointer shape is limited to the size of a cursor. The default image for 
graphics mode is a bit-mapped representation of an arrow pointing diagonally up 
to the right. It is recommended that graphics application are developed using the 
Presentation Manager, which makes available advanced facilities for creating and 
changing the shape of the mouse pointer. 

The graphics pointer image was designed with the CGA in mind. For this reason 
the same pointer image is used both in medium (320x200) and high (640x200) 
resolution modes. The image can contain up to 4 colors in medium resolution. 
Two colors, black and white, are permitted in the high resolution mode. 
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The pointer device driver requires that the bit-mapped image for the mouse 
pointer be very strictly defined. A pointer image is defined by two separate data 
structures: a buffer containing the bit-map values, and a pointer definition record. 
The structure of the pointer definition record is as follows: 


struct | 

unsigned TotLength; /* total lengthe of the bit-map 
buffer */ 

unsigned Col; /* pixel width of the image */ 

unsigned Row; j/* pixel height of the image */ 

thsiened Cold0ffget: /* horizontal offset to the 
Hot-Spot */ 

unsinged RowOffset; /* vertical ofiget to the Hot- 
Sour. *% 


The field TotLength specifies the length in bytes of the bit-map buffer. Coland 
Row specify the width and height of the image. In graphics mode, the unit of 
measurement is a pel. In text mode, the number of character cells is used. For 
example, in text mode the largest width and height that can be declared is 1 (which 
stands for 1 column and | row, or the size of a cursor). In graphics mode, 
depending on the resolution, the width and height can be 8 x8 pels, or even much 
larger. 

The fields ColOffset and RowOffset define the actual current mouse position 
relative to the upper left hand corner of the pointer shape image. The actual 
mouse position is also called the hot-spot. To really understand the significance of 
these fields, one must first understand the difficulty involved in determining the 
actual position of the mouse in graphics mode when a pointer image is used. In 
graphics mode, the pointer shape is usually a bit-mapped representation of an 
object (e.g., an arrow, an hour-glass, etc.). This picture takes up an area of about 
16x 16 pixels which is a larger than the actual location of the mouse which isa pixel 
coordinate (e.g., 0 x 0 is the upper left corner of the screen and 639 x 199 is the 
lower right corner of screen). ColOffsetand RowOffset specify the actual location of 
the mouse hot-spot as a displacement within the mouse pointer image. For 
example, if the ColOffset has a value of 5 and RowOffset has a value of 15, the hot- 
spot is 15 horizontal pixels, and 3 vertical pixels from the upper left-hand corner 
of the image. When a program calls MouReadEventQueue to determine the 
positon of the mouse, the driver calculates it using the upper-left corner coordi- 
nates of the bit-mapped image along with the ColOffsetand RowOffset values. When 
defining the pointer shape, a meaningful hot-spot should be chosen. For example, 
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DefGrph Struct ;default graphics pointer 


ANDmask DB 11111111B,11000011B ;default graphics ptr 
DB 11111111B,10000011B ;AND mask 
DB 11111111B,00000011B 
DB 11111110B,00000011B 
DB 11111100B,00000011B 
DB 11111000B,00000011B 
DB 11110000B,00000011B 
DB 11100000B,00000011B 
DB 11000000B,00000011B 
DB 10000000B,00000011B 
DB 11110000B,00000011B 
DB 11110000B,00000011B 
DB 11100000B,00111111B 
DB 11100000B,01111111B 
DB 11100000B,01111111B 

XORmask DB 00000000B,00000000B 
DB 00000000B,00010000B 
DB 00000000B,001 10000B 
DB 00000000B,01110000B 
DB 00000000B,11110000B 
DB 00000001B,11110000B 
DB 00000011B,11110000B 
DB 00000111B,11110000B 
DB 00001111B,11110000B 
DB 00011111B,11110000B 
DB 00000001B,11110000B 
DB 00000011B,00010000B 
DB 00000011B,00000000B 
DB 00000110B,00000000B 
DB 000001 10B,00000000B 
DB 00000000B,00000000B 





Figure 15.1 Bit-emapped Mouse Pointer Image 


if the pointer shape is an arrow, the hot-spot should be at the tip of the arrow. 
The bit-mapped image of the pointer shape is maintained in a memory buffer. 
This bit-map buffer is divided into two areas, the AND mask and the XOR mask of 
the bit-mapped image. Each pixel appearing on the screen is represented by 
combining corresponding bits from each area. When generating the mouse 
pointer shape image, the pointer driver combines the AND and XOR masks. If the 
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resultant bit is 0, the pixel is off; if itis 1 the pixel ison. The pattern on/off pixels 
creates an image on the screen. 

When the pointer driver examines the image buffer, it first determines the 
width and height of the pointer image area using the pointer definition record, 
then the AND and XOR mask halves of the memory buffer are examined. In order 
to understand this better, examine the way in which the default graphics image is 
specified. Each mask (AND and XOR) is a 32 byte block, representing a 16 x 16 
pixel area. Figure 15.1 contains both halves of the bit-mapped representation of 
the default mouse pointer image. 

The pointer definition record for Figure 15.1 would be: 


Total Length 64 bytes (32 bytes for each mask area) 


Col 16 pixels 

Row 16 pixels 

Col0ffset 13 pixels from the upper left corner 

RowOffset 2 vertical pixesl from the upper left 
corner 


The default pointer shape is defined for the CGA high-resolution mode. This 
is why a pixel can only have two colors: black (off) or white (on). In the EGA’s high- 
resolution mode, the pointer shape can contain up to 16 colors. This means that 
the pointer shape must be defined in multiple bit planes on the EGA board to take 
advantage of the available colors. Using MouSetPtrShape to create a multiple bit 
plane mouse pointer is very difficult, requiring the program to directly manipulate 
the EGA registers which brings up the issue of forcing the application to save the 
video context whenever the user switches sessions (see Chapter 16). This proce- 
dure is very complicated, and its discussion is beyond the scope of this book. We 
recommended that the Presentation Manager should be used to create a mutlti- 
colored mouse pointer image. 


MouGetPtrShape and MouSetPtrShape 


MouGetPtrShape returns the current image buffer, and pointer definition 
record. MouSetPtrShape uses the image buffer and the pointer definition record 
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passed to it by the program to create a new pointer shape for the mouse. Both 
functions require the mouse handle returned by MouOpen. 

The values of the two masked areas of the mouse pointer in graphics mode were 
described earlier. In text mode, the default pointer shape is defined as a 1 x 1 
blinking cursor. The pointer image consists of four bytes with the following values. 


AND mask FFFF 


XOR mask 7720 


The mask value is the same as the character attribute byte of an screen character 
(please refer to Chapter 13 for the possible values of these masks). 

Both functions expect the same parameters: the mouse handle (MouHandle), 
a buffer pointing to the two masked areas of the image (PirBuffer), and the pointer 
definition record (PirDefRec). MouGetPtrShape copies the two masked areas for 
the image to a memory buffer specified by PirBuffer. It expects the length of this 
memory buffer to be specified in the YotLength field of the pointer definition 
record. MouSetPtrShape uses the three parameters passed to it to construct the 
pointer shape. 

Once the new pointer shape has been set with MousSetPtrShape it may not 
immediately be displayed on the screen. The pointer driver waits until the next 
time it is instructed to draw the pointer (e.g., when the mouse is moved, if the 
pointer is currently displayed and the next time the pointer is drawn, if it is not 
currently displayed). ‘To insure that the new pointer shape is immediately 
displayed the program should call MouRemovePtr and MouDrawPtr after defining 
the new shape. 


MouGetPtrShape (PtrBuffer, PtrDefRec, MouHandle) 


MouSetPtrShape (PtrBuffer, PtrDefRec, MouHandle) 


char far *PtrBuffer; /* pointer to image buffer */ 
struct PtrImage far *PtrDefRec; /* pointer to pointer defintion record */ 


unsigned MouHandle; /* mouse handle */ 
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Example 


/* PTRSHAPE.C 


This program demonstrates how to use MouGetPtrShape to determine the 
bit-mapped image values and pointer definition record for both text and 
graphics mode 


ny 


+#include “doscalls.h” 
include “subcalls.h” 


/* screen modes */ 


4#tdefine MONO 0 
+#define NON MONO 1 /* text mode */ 
#tdefine GRAPHICS 2 /* graphics mode */ 


+#define COLORBURST4 /* eolorburet enabled */ 
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#fdefine ERROR_VIO_MODE 
355 /* unsupported screen mode */ 


main() 


unsigned MouHandle;/* parameter for MouGetPtrShape */ 
(hear PtrBuffaer [100]: 
struct Ptrimage PtrDefRec; 


struct ModeData VioMode:/* parameter for VioGetMode */ 
char def; /* default video mote */ 


unsigned ret, i,j, j2; 


ret = MOUOPEN( (char far *)0O, 
(unsigned far *) &MouHandle) ; 

if (ret) { 
printf (“\nMouOpen failed: %d”, ret) ; 
DOSEXIT(1,0); 


PtrDefRec.TotLength = 100; 

printf (“\nGetting the pointer shape in text mode.”) ; 

ret = MOUGETPTRSHAPE( (unsigned char far *)PtrBuffer, 
(struct PtrImage far *)&PtrDefRec, 
MouHandle) ; 

if (ret) { 
printf (“\nMouGetPtrShape failed: %d”,ret); 
DOSEXIT (1,0); 


for (1-0; 4% Ptrbefkec .TotLength - 1; i+=2) { 
{= (ant) PerButter [i]: 
{22> (int) PtrBuffer [irl]; 
pfintt (* \aH02s 202K" 7. 72): 

} 


printf (“\nTotLength: %d Column: %d Row: %d ColOffset: %d RowOffset: %d”, 
PtrDefRec.TotLength, 
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PtrDefRec.Col, 
PtrDefRec.Row, 
PtrDefRec.ColOffset, 
PtrDefRec.RowOffset) ; 


printf (“\nGetting the pointer shape in graphics mode”) ; 
VioMode.length= sizeof (struct ModeData) ; 


if (ret =VioGetMode(&VioMode, 0)) { 
printf (“\nVioGetMode failed: %d”, ret) ; 
DOSEXIT(1,0)3 

def =VioMode.type; 


VioMode.type =(char) (GRAPHICS | NON_MONO) ; 


if (ret = VIOSETMODE (&VioMode, 0)) { 
printf (“\nVioSetMode failed %d”, ret) ; 
DOSEXIT (1,0); 

} 

ret = MOUGETPTRSHAPE( (unsigned char far *)PtrBuffer, 
(struct Ptrimage far *)&PtrDefRec, 
MouHand1le) ; 

if (ret) { 
printf (“\nMouGetPtrShape failed: %d”, ret) ; 
DOSEXIT (1 ,.O) % 


VioMode.type=def; 

if (ret = VIOSETMODE(&VioMode, 0)) { 
printf (“\nVioSetMode switch back failed %d”,ret):; 
DOSEAIT(EL,O): 


for (1-0; i < PirbefRec.TotLength - 1; it=2) 
printf(“\n%04X %04X”, (unsigned) PtrBuffer [i], 
(unsigned) PtrBuffer[itl1]); 


printf£(“\nTotLength: %d Column: %d Row: %d ColOffset: %d 
RowOffset: %d”, 


Mouse API Functions 633 


PtrDefRec.TotLength, 
PtrDefRec.Col, 
PtrDefRec.Row, 
PtrDefRec.ColOffset, 
PtrDefRec.RowOffset) ; 


MOUCLOSE (MouHandle) ; 


Collision Area: MouDrawPtr and MouRemovePtr 


A collision area is a screen area where the mouse pointer image cannot be 
drawn. The function MouRemovePtr allows the application to define ascreen area 
as a collision area. If the mouse image is currently in the collision area, at the 
completion of the function its image disappears (moving the mouse out of the 
collision area causes it to reappear). Only one collision area can be effective at one 
time. Issuing MouRemovePtr again defines a new collision area and nullifies the 
previous one. When multiple application within a session share the mouse handle, 
any process can issue this function, but the latest defined collision area simply 
replaces the previous one. Any collision area defined is only effective within the 
current session and has no effect within other sessions. 

The function MouDrawPtr notifies the mouse driver that any collision area 
previously set is no longer effective, allowing the mouse pointer image to be drawn 
on the entire screen area. It negates the effect of MouRemovePtr. To set-up 
another collision area, the function MouRemovePtr must be reissued. When the 
mouse is opened, the default collision area is the entire screen. During the initial 
state, the mouse pointer image does not appear on the screen. The application 
must use either MouDrawPtr to cancel the collision area or MouRemovePtr to 
define a smaller collision area. 

These two functions are only applicable in full draw support mode; in disabled 
mode the application is responsible for managing collision areas itself. 

The function MouDrawPtr expects only one parameter, the mouse handle 
previously returned by MouOpen. The function MouDrawPtr has no effect if a 
collision area has not been previously defined. 

The function MouRemovePtr expects the mouse handle and a pointer to a data 
structure containing the coordinates which define the collision area: upper left 
row, upper left column, lower right row, and lower right column. The values for 
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these coordinates must be either in row/column numbers or in pixels depending 
on the current mode of the video adapter. The function VioGetMode can be used 
to determine the video mode. The values for these coordinates must fall within the 
actual video screen area. Any attempt to go beyond the screen area generates an 
error. In text modes, the range of row and column numbers is dependent on the 
maximum number of rows and columns support by the particular mode. In 
graphics mode, the range also depends on the horizontal and vertical size 
supported by the current display mode. 
The format of the coordinate data structure is as follow: 


struct Collision_Area { 
unsigned UpLeftRow; /* topper Lert row */ 
unsigned UpLeftCol; /* upper left column */ 
unsigned LowRightRow; /* lower right row */ 
unsigned LowRightCol; /* lower right column */ 


MouRemovePtr (PtrArea, MouHandle) 


struct Collision_Area far *PtrArea; /* pointer to collision area */ 


unsigned MouHandle; /* mouse handle */ 





MouDrawPtr (MouHandle) 


unsigned MouHandle; /* mouse handle */ 
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Mouse Positions: MouGetPtrPos and MouSetPtrPos 


The function MouGetPtrPos determines, and function MouSetPtrPos sets, the 
mouse pointer position. Setting the mouse pointer position in full-draw support 
mode initializes the mouse pointer image at a specific screen coordinate no matter 
the current state of the mouse or its actual physical location on the desk. Setting 
the mouse pointer in disabled mode changes the location of the virtual mouse 
pointer. The new pointer coordinates must conform with the current display 
mode and the dimensions of the screen. In graphics modes, the coordinates must 
be in pixels and in character column/row numbers for text modes. The function 
MouSetPtrPos does not override any collision area thatis still active. If the specified 
pointer coordinates lie within a collision area, the mouse pointer is not displayed. 
It will be displayed once the mouse has been moved out of the collision area. 

Both functions expect the same parameters, the mouse handle and a pointer to 
memory block containing the coordinates to be returned in case of MouGetPtrPos, 
or to be set for MouSetPtrPos. In graphics mode, the coordinates are returned in 
pixels and in text mode, they will be in collumn/row numbers. The structure of 
the memory block for the coordinates is defined as: 


Btruct. Preboc { 
unsigned RowPos; /* Pow position. */ 
unsigned ColPos; /* eolimn position */ 


} 


MouGetPtrPos (PtrPos, MouHandle) 


MouSetPtrPos (PtrPos, MouHandle) 


struct PtrLoc far *PtrPos; /* pointer to the coordinate structure */ 


unsigned MouHandle; /* mouse handle returned by 
MouOpen */ 
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Mouse Device Status: MouGetDevStatus and 
MouSetDevStatus 


MouSetDevStatus allows an application to change the mode of the pointer draw 
device driver and to switch the unit of motion measurement from absolute 
coordinates with pixel or row/column numbers to relative coordinates using 
mickeys. Changing the mode of the pointer draw driver from full-draw support 
mode to disabled state mode is crucial and must be done before the video adapter 
is switched from text mode to graphics mode. Otherwise, the mouse driver is 
rendered inactive for the session. Please refer to page 2 for a detailed discussion 
of mode switching. 

Changing the unit of measurement only affects the row and column position 
numbers returned by MouReadEventQue. Please refer to page 14 for more 
information. 

MouGetDevStatus simply returns the current status of the mouse driver. Both 
functions expect the same parameters: a mouse handle and a pointer to a memory 
block containing the mouse device status information being passed or to which 
information is to be returned. The memory block is a 2-byte (WORD) or an 
unsigned bit-masked value. 


MouGetDevStatus (DeviceStatus, MouHandle) 


MouSetDevStatus (DeviceStatus, MouHandle) 


unsigned far *DeviceStatus; /* pointer to the device status */ 


unsigned MouHandle; /* mouse handle */* 
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Other Mouse Functions 


Several mouse functions are used for query purposes. The function MouGet- 
NumButtons returns the number of buttons installed on the physical mouse. 
MouGetHotKey returns the current mouse event sequence which acts just as a Ctrl- 
Esc code used by the Session Manager to start the program selector. An application 
can also set the “hot-key” on the mouse using MouSetHotKey. A hot-key sequence 
can be initiated by pressing one mouse button, or a combination of several mouse 
buttons. 
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MouGetNumButtons 


MouGetNumButtons simply returns the number of buttons currently sup- 
ported by the mouse driver for that particular mouse. This usually means the 
number of buttons on the mouse. The function expects a mouse handle, and a 
pointer to an unsigned ora WORD memory variable where the number of buttons 
will be returned. 


MouGetNumButtons (NumberOfButtons, MouHandle) 


unsigned far *NumberOfButtons; /* pointer to the number of buttons */ 


unsigned MouHandle; /* mouse handle */ 





MouGetHotKey and MouSetHotKey 


Functions MouGetHotKey and MouSetHotKey are not mentioned in the IBM 
OS/2 Technical Reference, but they are discussed in detail in the Microsoft 
OS/2 Programmers Reference. MouGetHotKey returns the mouse event which 
triggers the Session Manager to load the program selector. MouSetHotKey sets the 
mouse event that would be this hot-key. After calling this function the mouse hot- 
key sequence is triggered when the user presses a specified button or combination 
of mouse buttons. Setting the hot-key changes the mouse hot-key sequence for 
every session in the system, and not just the current one. 

Both functions expect the same parameters, a mouse handle and a pointer to 
a memory block containing the bit-mask values for the hot-key sequence. Call this 
the button mask. The button mask is returned to this memory location by the 
function MouGetHotKey. The function MouSetHotKey receives the button mask 
in this memory block and uses it to change the current hot-key sequence. 
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MouGetHotKey (ButtonMask, MouHandle) 


MouSetHotKey (ButtonMask, MouHandle) 


unsigned far *Button Mask; /* pointer to the button mask */ 


unsigned MouHandle; /* mouse handle */ 





For ButtonMask, if bit 0 is set, there will be no “hot-key” sequence for the mouse. 
In order to define “the pressing of button 1” as the hot key, bit 1 should be set and 
the rest should be off. If the simultaneous pressing of of button 1 and 2 are the 
definition of the “hot-key”, bits 1 and 2 should be set while the rest should be off. 


640 Advanced Programmer's Guide to OS/2 


Mouse Support Under the Presentation 
Manager 


The Presentation Manager will provide an advanced set of API functions for 
mouse applications. Graphics applications will not have to deal with the problems 
of of drawing or moving the mouse pointer image. The Presentation Manager will 
automatically move the mouse pointer, and pointer images will be created through 
a utility it provides. The implementation of the mouse interface within an 
application will be much simpler, because the application will not need to keep 
track of the current mouse position. The PM will provide utilities that will allow 
an application to define menus and the PM will automatically notify the applica- 
tion of the user’s selection. Graphics mode applications that use the existing API 
will run finé under the PM. The PM will synchronize access to the mouse among 
several applications running within the same session. 

Text-mode applications will be able to run under the Presentation Manager 
unaltered. The PM will provide all the necessary synchronization. However, the 
PM provided API function may provide additional abilities that the you may wish 
to take advantage of. In this case you will have to rewrite parts of your application 
to use the additional API provided by the PM. 

All the functions in this chapter are compatible with the Presentation Manager 
except for functions MouSetPtrShape if it is used to define a pointer shape in 
graphics mode. 


Family API Mouse Support 


Unfortunately the OS/2 FAPI interface does not support mouse API functions 
in real mode. This means that it will not be easy to develop mouse applications that 
will run in both real and protected modes. In protected mode an application can 
use the the full complement of mouse API functions. In real mode, however, an 
application must use INT 33H function calls. Devoloping a mouse application that 
runs in both modes will entail conditionally executing INT 33H calls when in real 
mode, and MOUxxx API calls in protected mode. The overhead involved in doing 
this may be prohibitive. Generally speaking, mouse applications will require 
separate real mode and protected mode applications, as they cannot use the same 
API. 


Mouse API Functions 641 


Supported Mouse Devices 


The initial release of OS/2 contains the following device drivers which can be 
used to support a variety of mouse devices. This list includes the driver file names 
and the type of mouse each driver supports. 


Driver File Names Mouse Device for PC/AT and AT Compatibles 


MOUSEAOO.SYS 
MOUSEAOL.SYS 


PC-Mouse by Mouse Systems, serial, 100 ppi. 
Visi On Mouse, serial, 100 ppi 


MOUSEA02.SYS 
MOUSEAO2.SYS 
MOUSEAO3.SYS 
MOUSEA0O3.SYS 
MOUSEAO04.SYS 
MOUSEBO0.SYS 
MOUSEBO1.SYS 
MOUSEBO02.SYS 
MOUSEB03.SYS 


Microsoft Serial Mouse, 100 ppi 

Microsoft Serial Mouse, 200 ppi 

Microsoft Bus Mouse, 100 points per inch (ppi) 
Microsoft Bus Mouse, 200 ppi 

Microsoft Inport Mouse, 200 ppi 

PC Mouse by Mouse Systems, serial, 100 ppi 
Visi On Mouse, serial, 100 ppi 

Microsoft Mouse, serial (100 or 200 ppi) 

IBM PS/2 In-Processor Mouse, 200 ppi 





Most serial mouse device drivers attempt to exclusively capture the interrupt of 
the asynchronous port attached to the mouse. During system installation, the 
system always attempts to install the mouse driver before installing the asynchro- 
nous port driver, because if the driver cannot exclusively control the mouse, the 
installation of the driver will fail. This allows the mouse driver to take control of 
the communiation port it’s plugged into before any other drivers. When the 
asynchronous port driver is subsequently initialized, it simply ignores the port, 
recognizing that asynchronous communication is not possible through it. This 
ensures that an interrupt meant for the mouse driver will not be trapped by an 
asynchronous driver. 

The PS/2 mouse is an on-board mouse. Access to this mouse is through the new 
ABIOS pointing device commands supported by the PS/2. The PS/2 mouse driver 
has exclusive control of the asynchronous I/O port, but shares the interrupts for 
the device. 


Chapter 16 





Advanced Video Functions 


application. In this chapter we will cover API functions used to implement 
advanced video functions. We will present several distinct sets of API functions 
which allow an application to perform the following advanced video functions: 


: n Chapter 13, we explained how to use video functions in a text-based 


® Allow a background process to “pop-up” during the execution of a fore- 
ground process, in order to inform the user of an important event, or to 
accept user input. 


= Allow a text mode application to directly manipulate its logical video 
buffer, instead of using the protocol imposed by the regular API VIO calls. 


=" Download screen fonts to the video adapter. 


In addition, this chapter will introduce some of the intricacies involved in 
writing graphics mode applications for OS/2. OS/2 does not provide API 
functions for applications to create and manipulate graphics objects. These 
functions are available in the extended API set provided by the Presentation 
Manager. It is recommended that graphics applications use the PM functions 
because they include many features which reduce development time (i.e., support 
for various types of printers, graphics adapters, and advanced graphics drawing 
and painting capabilities). Ihe only real alternative for graphics-based applica- 
tions development is to directly manipulate the video adapter to provide graphics 
functions. 

Directly manipulating the video adapter is a complicated affair under OS/2 
because the video adapters currently being used in AT and PS/2 systems were 
designed for use with a single-tasking system. These adapters’ hardware and 
firmware assume that only one process controls the adapter, so they have no built- 
in features for multitasking. When the API functions provided by OS/2 or the PM 
are used, then OS/2 or the PM will handle the synchronization necessary to share 
the video adapter among several processes (the PM allows several applications to 
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share the same screen simultaneously; the OS/2 Session Manager allows many 
applications to run simulteaneously, each on its own screen). If an application 
wishes to manipulate the video adapter by itself it must take over many of the 
services formerly provided by OS/2 or the PM. In addition, a graphics application 
that does not use the PM functions cannot run as a concurrent window under the 
Presentation Manager (though it can run as a separate screen). 

In most cases it is preferable for the programmer to submit to Presentation 
Manager structure requirements, rather than attempting to replace them with a 
graphical interface of their own. In any case, we will not discuss how to manipulate 
any particular video adapter in this chapter. The programmer should refer to the 
technical reference for his or her video adapter in order to obtain this information. 


Logical and Physical Video Buffers 


Video adapters are equipped with on-board memory which is used to store the 
definition of the characteristics of each picture element (pel or pixel) that is to 
appear on the screen. A pel is usually a single dot on the screen. A number of pels 
taken together compose a screen image. When all the screen dots are viewed 
together, their combined colors create ascreen image’s color and shading. We can 
think of a blank EGA screen as being composed of 640 x 350 dots all of which are 
black. Suppose a square is drawn on the video screen. It is composed of many pels 
connected in four lines to form the image of a square. The pels forming the line 
of the square have to be specified as a color other than black in order for the eye 
to differentiate the square from the rest of the screen. 

Depending on the type of adapter being used, each pel can be one of many 
colors. The larger the video memory buffer installed on the adpater, the more 
colors a pel can assume. For example, in order to represent a pel with 16 colors, 
each pel requires 4 bits of RAM. Multiply this by the number of pels the adapter 
can produce, and we have the approximate amount of RAM on the adapter. The 
CGA only contains 16K of memory which handles one screen image with a 
resolution of 640 x 200, two-color pels. The EGA contains up to 256K of video 
memory, enough for two video pages with a resolution of 640 x 350, 16-color pixels. 
The VGA has 256K of on-board RAM and can handle up to two pages of 640 x 480 
resolution with 16-color pixels, as well as a mode that provides two pages with 320 
x 200 resolution 256-color pixels. The memory installed on the adapter is referred 
to as the physical video memory buffer (PVB). 

The physical video buffer also comes into playin the text modes. Each character 
which is to appear on the screen requires 2 bytes of space on the PVB: one byte for 
its ASCII value and the other for its character attributes (see Chapter 1). 
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OS/2 gives applications that use the API video subsystem functions with special 
services that allow many applications to share the same physical video buffer. The 
most important of these is the session screen group mechanism, which provides 
each session with its own logical video buffer. Generally, an application uses the 
functions provided by the video subsystem to manipulate its logical video buffer. 
When this application is switched into the foreground session, its logical video 
buffer is loaded into the physical video buffer, and the information displayed 
within it appears on the display screen. 

The video subsystem calls are implemented through dynamic link routines. 
The execution time of these routines is fast, but perhaps not fast enough for the 
needs of certain applications. OS/2 provides such application with functions that 
bypass the usual API interface, allowing an application to instruct the video 
subsystem to directly manipulate the logical video buffer. Because the application 
only manipulates its own logical video buffer, OS/2 still handles the synchroniza- 
tion required to run along side others within the multitasking environment. 
However, because the Presentation Manager requires that applications do all their 
video I/O using either its functions or the standard video subsystem functions, an 
application which directly manipulates its logical video buffer cannot run as a 
window under the Presentation Manager. Such an application will run, though, 
as a separate screen under the PM. 

Applications can implement their own advanced graphics functions by directly 
manipulating the video adapter’s physical video memory. For CGA boards this is 
a simple enough matter, but manipulation of EGA and VGA boards in the 
advanced graphics modes requires that the video card registers themselves must 
be manipulated.’ Applications that directly manipulate video boards must handle 
certain tasks that are usually handled by the video subsystem by themselves. For 
example applications which manipulate the physical video memory must save a 
copy of the physical video buffer when they are switched out of the foreground, and 
then refresh the physical video buffer when they are switched back in. OS/2 
provides a set of functions (which we will discuss later), that allow an application 
to do this. 

As we mentioned, this chapter does not cover the intricacies of writing advanced 
graphics functions under OS/2. We merely discuss the issues that have to be 
addressed by an application which wishes to do this while running alongside other 
applications in OS/2’s multitasking environment. 


"Applications which wish to directly manipulate the EGA or VGA boards in the advanced video modes will have 
to run as IOPL routines (see chapter 19). 
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Background Pop-Ups 


We discuss this capability throughout the book. “Pop-up” facilities under 
OS/2 work like TSR* programs under DOS. Under DOS, Terminate and Stay 
Resident programs are invoked by a certain “hot-key” sequence. The program 
pops up on the screen during the execution of another program, takes over the 
processor, then returns control to the original program when it is dismissed. 
Under OS/2 background processes, or sessions can interrupt the foreground 
process. The difference between OS/2 and DOS is that OS/2 provides an ordered 
environment in which requests for pop-ups are synchronized, while under DOS 
pop-ups are handled in a haphazard manner which often causes problems when 
many ISR programs are loaded into memory. 

Under DOS, TSR programs are a nifty way to approximate multitasking in a 
single-tasking environment. Under OS/2, however, multitasking is inherent: 
several processes run at once with little programming effort, and there is a standard 
user interface to switch between sessions. Video pop-up functions should generally 
only be used by processes running in background sessions to inform the user about 
events that might require his or her intervention (e.g., to report the occurrance of 
an error or present a message stating that an operation has been completed). In 
addition, OS/2’s device monitor facility allows a background process to trap certain 
key-stroke sequences and react to them, often with a pop-up. See Chapter 20 for 
a discussion of device monitors. 

The background pop-up is also used by OS/2 for hard error processing. Ifa 
hard error is detected during the execution of a program, OS/2 issues VioPopUp 
which allows a background process to assume control of the video screen, the 
keyboard, and the mouse. This background process displays a hard error message 
and requests the user’s.response. After the user has responded, OS/2 issues 
VioEndPopUp to release control of the foreground session. The program running 
in the previous foreground session then continues its execution. 

A background process requiring a pop-up behaves in the same way as OS/2 does 
for error processing. It first first requests a video pop-up with VioPopUp. If the 
function returns successfully, it can display its messages and/or request user 
inputs. After it has displayed its message, or the user has entered the desired input, 
the process issues VioEndPopUp to return control of the foreground session to the 
process that had previously controlled it. 


*This wasa program that once loaded was retained in RAM memory, even when it was not running so thatit could 
be invoked again immediately without the need to reload it into memory. 
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Essentially, VioPopUp allows a background process to be a foreground process 
temporarily. We emphasize temporarily, because a background process should use 
the pop-up capability only to notify the user of an important event. Constant pop- 
ups by background processes are very disruptive. Keep in mind that during a pop- 
up the previous foreground session continues executing, but is treated as a 
background process. Any Vio, Kbd, or Mou functions calls made by this process 
are blocked by the Session Manager until the background process making the pop- 
up releases control of the foreground session. Session switching is also disabled 
during a pop-up call. The user cannot switch to another session until the 
background process issues VioEndPopUp. 


Using VioPopUp and VioEndPopUp 


VioPopUp allows a background process to request permission from the Session 
Manager to display a message on the screen. Once approved by the Session 
Manager, the process has temporary control of the foreground sesson including 
the physical keyboard, mouse, and video screen. Pop-up calls use a special session 
and therefore do not use the normal logical buffers used by the background 
session. This means that the thread that calls VioPopUp should wait until the 
function returns with a successful return code before sending messages to the 
screen with Vio calls. Otherwise these calls will be directed to the regular logical 
video buffer instead of the special pop-up buffer (this output would not be 
displayed until that session was really switched into the foreground). Any Mou or 
Kbd calls issued before a succesful return code is received are intercepted and 
halted by the Session Manager just as if they were called by a background process. 
After a successful return with VioPopUp, any subsequent Vio, Mou, or Kbd calls are 
directed to the pop-up session rather than the background session until the 
process issues VioKndPopUp. 

OS/2 imposes several limits on the use of VioPopUp. Only one pop-up can be 
in effect at any time. Ifa video pop-up is currently in place, and another process 
requests a video pop-up, this process either is forced to wait until the completion 
of the first pop-up, or it receives an error code identifying the problem. Also, only 
the process that issued VioPopUp is brought to the foreground. The status of all 
other processes within that background session is unchanged. Any attempt by 
these processes to use Kbd, or Mou is blocked by the Session Manager. 

The function DosExecPgm cannot be issued during a video pop-up session. 
This means that during the time of the pop-up, the background process cannot 
spawn any other process. Nor can the background process manipulate the physical 
video buffer during a pop-up. 
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The following is a list of VIO calls that can be used during a pop-up: 


VioEndPopUp VioSetCurPos 
VioGetConfig VioSetCurType 
VioGetCp VioSetCp 
VioGetFont VioSetFont 
VioGetAnsi VioSetState 
VioGetState VioWrtNChar 
VioGetCurPos VioWrtCharStr 
VioGetCurType VioWrtNAttr 
VioGetMode VioWrtNCell 
VioReadCharStr VioWrtCharStr 
VioReadCellStr VioWrtCharStrAtt 
VioScrollRt VioWrtCellStr 
VioScrollUp VioWrt TTY 
VioScrollDn VioScrollLf 


Microsoft and IBM do not list the KBD and MOU functions that can be called 
during a pop-up. The programmer will have to compile a list of allowable functions 
through trial and error. This is not intended to discourage. We have tried most 
of the KBD and MOU functions (that were necessary to obtain input from the user 
such as KbdStringIn, KbdPeek, KbdCharIn, and MouReadEventQueue) in the 
pop-up mode and they work fine. 

Ifan application substitutes its own routine for VioPopUp using the VioRegister 
function, this replacement function will only be executed if the process containing 
this routine is currently in the foreground. If the process containing the new pop- 
up routine is in the background, then the default VioPopUp set up by the video 
subsystem is used instead. If, during the pop-up, the interrupted application has 
a keyboard or mouse device monitor installed, that monitor will not receive any 
data. 


VioPopUp 


VioPopUp allows for two types of pop-ups: transparent and non-transparent. A 
non-transparent pop-up switches the video mode of the foreground session to a 
text mode (25 x 80 screen), clears the screen, and positions the cursor in the upper 
left corner. A transparent pop-up does not change the display mode or clear the 
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screen of the foreground session, and the cursor position remains unchanged. A 
transparent pop-up Is only possible if the foreground session is in text mode. If the 
foreground session is in a graphic mode or has issued a VioSavReDrawWait thread, 
the request for a transparent pop-up returns an error. 

VioPopUp expects two parameters, pop-up option and the video handle which 
is reserved for OS/2 and must be zero. The pop-up option is a bit-mask value 
specified by Options, a pointer to an unsigned or WORD (2-byte) variable. The 
possible bit values for Opizon are: 





VioPopUp (Options, VioHandle) 


unsigned far *Options; /* a pointer to the wait and pop-up 
options */ 


unsigned VioHandle; /* reserved, must be zero */ 
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VioEndPopUp 


VioEndPopUp is used to notify the Session Manager that the calling back- 
ground process wishes to end its pop-up session. Control of the foreground session 
is returned to the previous foreground process. At the completion of VioEnd- 
PopUp, any Mou, Kbd, and Vio calls made by the pop-up session are handled in the 
usual manner for background processes. 


VioEndPopUp (VioHandle) 


unsigned VioHandle; /* reserved and must be zero */ 





Example 


f® YLOPOPUP.© 
This program demonstrates how to use VioPopUp. 


You should run this program as a detached process via the com- 
mand 


DETACH VIOPOPUP. 
The program will set up a timer to remind it to pop-up every 2 


seconds. 
The program terminates after the third pop-up. */ 


include “doscalls.h” 
inelude “subcalls.h” 


#tdefine 
#define 
define 
define 
+#define 
define 


+#define 
define 
+#define 
+#define 


+#define 
+#define 


char SemName[] = 


VERT 0 

HORZ 1 

UPRT 2 

LWLF 3 

LWRT 4 

UPLF 5 

NOEXCLUSIVE 1 

ERR SEMTIMEOUT 121 i? 
VP_NOWAIT Ox0000 }* 
VP_WAIT 0x0001 ;* 
VP_OPAQUE 0x0000 f* 
VP_TRANSPARENT 0x0002 /* 


“\\SEM\\TIMER” : 


void box(x,y,.21,¥y1) 
insti ened x.y, 2l,yl% 


{ 


Static char border [6] 


Wid ame 


int row, 


*\xB3* . 
‘“\eDA” } 


== 


column: 


VIOGETCURPOS (&row, &column, 0) : 
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/* deranitien tor drawine box */ 


ob 


semaphore wait time out 


constants for VIOPOPUP */ 

Walt Of nO wet: option */ 

clear the screen */ 

do not clear the screen if text 


a 


mode 


A’ 720A *\eBE*.  \eCO', *\epo', 


VIOWRTNCHAR (&border [HORZ] , (yl-y-1),x,yt1,0); 
VIOWRTNCHAR (&border [HORZ] , (yvl-y-1),x1,y71,0): 
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For (2 xtlsi < xlsiti) { 
VIOWRTNCHAR (&border[VERT],1,i,y,0); 
VIOWRTNCHAR (&border [VERT] ,1,i,y1,0); 

} 

VIOWRTNCHAR (&border [UPRT] ,1,x,y1,0); 

VIOWRTNCHAR (&border [LWRT] ,1,x1l,y1,0); 

VIOWRTNCHAR (&border [UPLF] ,1,x,y,0); 

VIOWRTNCHAR (&border[LWLF] ,1 


’ 


mee clon ooo) 
VIOSETCURPOS (row,column,0O): /* move the cursor back to */ 
/* griginal position */ 


void WriteScreen(s,x,y) 
char *s; 
unsigned x,y; 
{ 
VIOWRTCHARSTRis,strlen(s), x.y. @):; 


main() 
{ 
long semhandle; /* semaphore handle, use for 
DosCreateSem */ 


long TimelInterval; 
unsigned timerhandle; 


unsigned i, ret, option; 


/* create a system semaphore */ 
DOSCREATESEM (NOEXCLUSIVE, 
/* non-exclusive system semaphore */ 
(long far *)&semhandle, 
(char far *)SemName) ; 


DOSSEMSET (semhandle); /* set the system semaphore */ 


/* start the asyne timer */ 
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TimeInterval = 2000L; /*. 1 second */ 


DOSTIMERSTART (TimelInterval, 
semhandle, 
(unsigned far *)&timerhandle) ; 


t=O /* waste for the semaphore té clear 
3 times */ 
;* then quit *¥ 


option= VP_WAIT | VP_TRANSPARENT; /* does not clear the 


sores */ 
7* end want wunitil pop up *7 
while (1) { 
rr 
DOSSEMWAIT (semhandle, (long) -1); 
/* watt till «lear */ 


if (ret = VIOPOPUP(é&option,0) ) 
DOSEXIT (1,1): 


/* making the box dimension more interesting */ 


box (St(2"*2) OF (2 "37,1207, 80rla 727): 


WriteScreen(“Example of VIOPOPUP” ,5+(i*2)+2,5); 
DOSSLEEP (1LO00L).; 
VIOENDPOPUP (0) ; 


DOSSEMSET(semhandle) ; 

if {i 2] 3) { 
print? (*\nStop Timer”): 
DOSTIMERSTOP (timerhandle) ; 
break; 
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Manipulating the Logical Video Buffer 


When an application writes a character string on the screen using the function 
VioWrtStr, it essentially asks the video subsystem to change the contents of its 
logical video buffer to represent the new character string. A logical video buffer 
is simply a large memory space which an application can manipulate ifit can obtain 
its starting address and length. The function VioGetBuf returns the starting 
address and length of the logical video buffer. 

Each character that appears on the screen requires two bytes in the logical video 
buffer. The first byte specifies its ASCII code and the second byte represents its 
attributes. The starting address of the LVB specifies the first character on the 
screen or the character at location 0, 0. The next byte specifies this character’s 
attributes. The next two bytes represent the character at location 0, 1 and so on. 
Since one screen of 25 x 80 dimensions only requires 4000 bytes of RAM, the logical 
video buffer can support several pages of text. For larger screens (like 43 x 80), 
fewer pages are possible. The number of pages simultaneously available to an 
application depends on the video adapter. The CGA only supports four 25 x 80 text 
pages. The EGA and VGA each support eight 25 x 80 text pages. Using 
VioScrollUp and VioScrollDn, the application can display the next or previous 
page of the LVB. 































4st WORD ASCII character Character video Screen position (R, C): 
code byte attribute byte 
ASCII character Character video Screen position (R, C): 
eng GRD code byte attribute byte 0,1 
3rd WORD ASCII character Character video Screen position (R, C): 
code byte . attribute byte 
) 
® 
6 
ASCII character Character video Screen position (R, C): 
BO tt OT code byte attribute byte 0,79 
ASCII character Character video Screen position (R, C): 
SIS! Meare code byte attribute byte 1,0 
© 
@ 
@ 


ASCII character Character video Screen position (R. C): 


Figure 16.1 Character representation and the logical video buffer 
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Changes made to the logical video buffer are not immediately displayed on the 
screen; the application must direct OS/2 to display the new logical video buffer 
using VioShowBuf. If the application is currently in the foreground session when 
it issues VioShowBuf, the logical video buffer updates the physical buffer and the 
changes made appear on the screen. If the session is in the background, however, 
none of the changes made to the screen are displayed on the screen until the 
session is switched to the foreground. 

It is up to the programmer to decide how often the application should call 
VioShowBuf to display the contents of the logical video buffer. VioShowBufis avery 
fast function, but if it is called too often, the screen can become difficult to read. 
In general, the function VioShowBuf should be called as often as the logical flow 
of the program demands, and no more. 

Direct manipulation of the logical video buffer is a powerful tool. The 
application has access to all parts of its video display buffer, and changes made to 
it are not displayed on the video screen until the application instructs OS/2 to do 
so. An OS/2 application manipulating the LVB does not need to concern itself 
with the actions of other screen groups. All the necessary synchronization is 
handled by OS/2. 

Using the functions VioGetBuf and VioShowBuf makes the program unable to 
run as a window in the Presentation Manager, but it can still run as a separate 
screen. VioGetBuf is also limited in that it does not support graphics mode. This 
is primarily because manipulating EGA and VGA adapters in their advanced 
graphics modes also requires manipulating their registers’. 


VioGetBuf 


VioGetBuf returns the starting address and the length of the logical video buffer 
that was previously created by the Session Manager for the session. The length of 
the buffer is the number of bytes or characters the screen can hold. This number 
depends on the dimensions of the screen, which can be determined using the 
function VioGetMode. Remember that each character is represented by two bytes. 


length of buffer = Number of rows * Number of columns * 2 


VioGetBuf returns a DWORD or a long value containing the selector and. 
starting offset of the LVB. The first WORD specifies the selector and the next 
WORD specifies the starting offset. 


Sif the application is running with a CGA, it can trick OS/2 by manipulating the video buffer in text mode, then 
switching to graphics mode using VioSetMode. The CGA adapter will simply translate the contents of the video 
buffer into a bit-mapped graphic. This technique, however, is not recommended. 
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VioGetBuf (LVBPtr, Length, VioHandle) 


long far *LVBPtr; /* pointer to a 4-byte (DWORD) block 
where the selector and starting offset 
will be returned */ 


unsigned far *Length; /* pointer to where the length value will 
be returned */ 


unsigned VioHandle; /* reserved, must be zero */ 





VioShowBuf 


VioShowBuf diplays the contents of the LVB for the foreground session on the 
actual video screen. If a background session issues VioShowBuf, no changes are 
made to the actual video screen until that session is switched to the foreground. 

VioShowBuf expects three parameters, the video handle, a starting offset within 
the LVB where the update will begin, and the length of the buffer in number of 
bytes. There are many possible values for starting offset and length depending of 
the area of the screen the application wants to update. The starting offset can be 
the actual starting offset returned by VioGetBuf and the length can be the length 
of the entire LVB. In this case, the entire screen will be updated with the contents 
of the LVB. VioShowBuf can also be used to update a smaller area of the screen. 
The starting offset specifies by Offset can be set to an address within the LVB 
representing the beginning, and the length of the buffer denotes the end of the 
update screen area. OS/2 will use the contents of the LVB starting from this 
address up to the number of bytes specified by Length rather than the whole LVB. 
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VioShowBuf (Offset, Length, VioHandle) 


unsigned Offset; /* starting offset within the LVB */ 


unsigned Length; /* pointer to where the length value will 
be returned */ 


unsigned VioHandle; /* reserved and must be zero */ 





Example 


_/* GETBUF.C 
This program demonstrates how to use the logical buffer to 


display data on the screen. Remember only text characters can 
be displayed using the logical video buffer 


The function WriteScreen displays a string at a specified X, Y 
coordinate using VIOWRTCHARSTR. 


We will write another routine which does the same thing but uses 
the address of the logical video buffer. 


a 
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#include “doscalls.h” 
#Finclude “subcalls.h” 


define MAKEUNSIGNED (1, h) (( (unsigned) (1))|( (unsigned) (h))<< 8) 


Ht}define NORMAL 7 

void cls() (* elear sereen */ 

{ 
ear -e[2 |< 
e(O) = * *y f* eall ce raplicate is a blank */ 
cll] = (char)NORMAL; 


/* with normal attributes */ 


/* elear sereen */ 
VIOSCROLLUP(G, O, -1, -1, <1, char far *)c, 0): 


void WriteScreen(s,x,y) 
char *e; 
unsigned x,y; 
{ 
VIGWRTCHARSTR(s,strlen({s), x.y. 0); 
} 


void WriteBuf(s,x,y,buf, Mode, attrib, length) 

char * <4: 

unsigned x,y; 

unsigned far *buf; 

struct ModeData *Mode; 

char attrib; 

unsigned length; /* lenmeath of video burtrer */ 


{ 
unsigned index; /* index anto the logical buffer */ 


unsigned i; 


index = Moda-2col * x + ¥3 





Advanced Video Functions 


woile (*6 l= *\o") 
buf [indext+] = MAKEUNSIGNED(*st+,attrib);: 


VIOSHOWBUF(0,length, 0); 


main() 


unsigned far *buf; 
unsigned length; 


struct ModeData ModeData; 

ghar 6 ([6u)% 

unsigned ret, i; 

cls(); 

ModeData.length = sizeof(struct ModeData) ; 
if (ret = VIOGETMODE(&ModeData, 0O)) { 


printf(“\nVioGetMode failed: %d”,ret) ; 
DOSEXIT(1,0); 


if (ret = VIOGETBUF((long far *)&buf, (unsigned far 
*leleneth, O)) 4 
orintt("\nVioGetBuf faileds “d",ret): 
DOSEXIT(1,0); 


WriteScreen(“Example of using VIOWRTCHARSTR”,2,0); 


WriteBuf (“Example of using VIOGETBUF”, 


oF /* = & y coordinate */ 
Os 

bat, /* buffer pointer */ 
&ModeData, /* mode infor */ 
(char) NORMAL, /* portial attribute */ 
length) ; /* length of butter */ 


DOSEXIT (1,0) : 
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Manipulating the Physical Video Buffer 


Direct manipulation of the physical video buffer by an application is feasible if 
the application can determine the starting address of that buffer. The function 
VioGetPhysBuf returns the starting address of this buffer. In text mode the 
physical memory is divided into a number of pages composed of ASCII code and 
attribute code sequences. Manipulating the CGA board in graphics mode is a 
simple matter, since the CGA board physical memory can only hold one screenload 
of graphics which is stored as a memory map large enough to represent 640 x 200 
pixels. Each pixel is represented by a single bit. 

In video modes 0 through 7 the EGA and VGA boards behave the same as the 
CGA. Butin the advanced graphics modes D, E, 10H, 12H, and 13H, the EGA and 
VGA boards divide each graphics page into several different planes. The memory 
addresses of locations on a page are not consecutive. In order to directly access 
EGA or VGA video memory, a graphics application must directly manipulate the 
registers located on the video adapter. ‘This means that such an application can 
only be implemented as an IOPL segment. Because of the complexities involved, 
we will not discuss the manipulation of the VGA and EGA registers here. The 
technical reference for each adapter should be consulted before making any 
attempt to directly manipulate these adapters with a graphics application. 

Any changes made to the bit values of the physical video buffer immediately 
change the context of the screen. This is because the application is actually 
changing the video adapter memory when it is changing the contents of the PVB. 
Because this is such a low-level access, an application that directly manipulates the 
PVB cannotrun as a window under the Presentation manager. It can, however, still 
execute as a separate screen. 

In order to directly manipulate the physical video buffer the application must 
be running in the foreground session. To insure that all processes conform to this 
rule, OS/2 requires thata graphics mode application issue the function VioScrLock 
to lock the video screen before accessing the physical screen buffer. VioScrLock 
returns an error if the session is in the background when this call is made. This 
mechanism guarantees that a background process cannot gain access to the 
physical buffer. When the application no longer needs to manipulate the buffer, 
it issues VioScrUnLock to relinquish its control over the physical buffer. 

All screen switching by the Session Manager is disabled while the foreground 
session has a lock on the physical video buffer with VioScrLock. This means that 
the user cannot switch to another session until the application issues VioScrUn- 
Lock. To keep this from inconveniencing the user, the application should unlock 
the screen as soon as it changes the PVB. Frequently locking and unlocking the 
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PVB makes the screen image look jittery, and the programmer should find a happy 
medium where the effects of these calls do not spoil the application appearance, 
but which still allows it to fulfill its objectives. 

In order to prevent an application from permanently locking up the screen, the 
Session Manager automatically performs a session switch, even if the screen is 
locked, a certain amount of time after the user specifies one, or if another 
application issues DosSelectSession. If the VioScrLock call times out in this 
manner, it has the same effect as if VioScrUnlock were issued. An application, 
however, should prevent this situation from arising by unlocking the screen as soon 
as possible. 


VioGetPhysBuf 


VioGetPhysBuf allows a foreground process to obtain the starting address of the 
physical video buffer. A background process cannot call this function. Use the 
function VioScrLock to determine whether a process is in the foreground or not. 

Depending on the adapter installed, the length of the PVB can be up to 256K, 
but the 80286 can only address memory segments up to 64K in length. Therefore 
DosGetPhysBuf returns several selectors for the PVB. The first represents the first 
64K segment, the second represents the next 64K segment and so forth with the 
last selector representing the remainder of the buffer. For an EGA, each of four 
selectors specifies a 64K segment of the PVB. The actual address of the selectors 
for EGA and VGA must fall within the range of A0Q000 to BFFFF. 

VioGetPhysBuf expects two parameters, a reserved video handle and a memory 
block where the values of the selectors and the length of the PVB will be returned. 
The data structure of the memory block is as follows (more selectors should be 
allowed for if the adapter contains more than 256K of on-board memory): 


struct PhysBbutbData. { 


long buf_start; /* startine selector and offset of 
the PVB-*/ 

long buf_length; /* Jeneth of the PYB */ 

unsigned selector_l; /* selector of first 64K segment */ 

unsigmed selector_2; /* selector of second segment */ 

unsigned selector_3; /* selector of third segment */ 

unsigned selector_4; /* selector of fourth segment */ 


Another way to define this structure is to put the selector lists in an array making 
it easier to access the selector within a C program: 


662 Advanced Programmer's Guide to OS/2 


Struct PhysBufData { 


long buf_start; {/* etartine selector and ofiset of 
the PVB */ 
long buf_length; /*-leneth of the PVE */ 


indigned selector([4|; /* selector lists */ 


} 


Buf_start specifies the starting selector and offset of the PVB. The length of the 
PVB is specified by buf_length. ‘The next four parameters specify the four selectors 
of the four 64K memory segments. This structure assumes that the maximum 
amount of RAM installed on the video adapter is 256K, a sufficient amount for the 
EGA and VGA. But if the video adapter used in the system contains more than 
256K, the programmer should add more selectors to this structure. It is the 
responsibility of the application to make sure that the data structure is large 
enough to hold all the possible selectors, because VioGetPhysBuf will simply return 
all selectors for the PVB without checking the length of the data structure. 


VioGetPhysBuf (Structure, VioHandle) 


struct PhysBufData *Structure: /* pointer to block where the returned 
info will be stored */ 


unsigned VioHandle; /* reserved, must be zero */ 





VioScrLock r 


Only the foreground process can have access to the physical video bufter. 
Permission to access it must be requested from the Session Manager, which does 
not grant access to background processes. The foreground process must issue 
VioScrLock and receive a successful return code before accessing the PVB. 
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Only one screen lock can be in effect at one time. If one thread in the 
foreground session locks the screen, and another thread in the same session asks 
to lock the screen, the second thread receives an error. Also, the thread that issues 
a successful VioScrLock must also issue VioScrUnLock. VioScrUnlock issued by 
another thread, even one in the same session, is ignored. 

VioScrLock expects three parameters: the video handle, the wait-option, anda 
pointer to a status byte. The wait option, WaztFlag, specifies whether the thread will 
wait until access to the PVB is possible. If the option is to wait, a and the called 
thread is in the background, it will be blocked until its session is switched to the 
foreground. | 

The pointer to the status byte, Status, is used to determine whether a lock was 
successful. ‘The status value is only meaningful if the call was returned without any 
error. 


VioScrLock (WaitFlag, Status, VioHandle) 


unsigned WaitFlag; /* wait or no-wait option */ 


char far “Status; /* pointer to returned status byte */ 


unsigned VioHandle; /* reserved and must be zero */ 
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VioScrUnLock 


VioScrUnLock notifies the Session Manager that the foreground process which 
issued VioScrLock no longer needs access to the physical video buffer. Normal 
session switching is resumed by the Session Manager. VioScrUnLock must be 
called by the same thread that called VioScrLock. Otherwise, VioScrUnLock will 
have no effect on the screen lock status. 


VioScrUnLock (VioHandle) 


unsigned VioHandle; /* reserved and must be zero */ 
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Example 


/* PHYSBUF.C 


This program demonstrates how to write directly to the physical 
video buffer and all the considerations required. 


The program demonstrates the following functions: 


VioGetPhysBuf 
VioScrLock 
VioScrUnlock 


In this example, we will only write to the video buffer in text 
mode, and not in graphics mode. Directly manipulating the 
physical video buffer in graphics mode requires the program to 
use function VioSaveReDrawWait to restore the screen whenever 
the session is switched back to the foreground. It is recom- 
mended that graphics applications use the Presentation Manager. 


This program also assumes a CGA. Manipulating the physical 
buffer of an EGA requires that the user manipulate the EGA 
registers. 


"5 


fHinclude “doscalls.h” 
include “subcalls.h” 
include <malloc.h> 
#Hinclude <dos.h> 


##Hdefine MONO 
}}define NON_MONO 
define GRAPHICS 
t}Kdefine COLORBURST 


/* text mode */ 
graphics mode */ 
/* colorburst enabled */ 


HH MOF © 
ss, 
+ 


constants for VioSecrLock */ 


4 
S 
+ 


4tdefine WAIT LOCK 
st}define NO WAITLOCK 0 
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ttdefine NORMAL 7 


#tdefine MAKEUNSIGNED(1, h) (( (unsigned) (1)) | ( (unsigned) (h))<< 8) 


void cls() /* elear acrean. */ 

{ 
char c[2]: 
elG) = * *. ~ /* cell to replicate is a blank */ 
c[1] = (char)NORMAL; /* with normal attributes */ 


/* clear screen */ 
VIOSCROLLUP(O, ©, *1, 9-1, -1, tehar far *})ea, 0) -« 


void WriteBuf(s,x,y,buf, Mode, attrib) 
char *s; 

unsigned x,y; 

unsigned far *buf; 

struct ModeData *Mode; 

chat aLtrib: 

{ 


unsigned index; /* index into the logical buffer */ 


unsigned ret; 
char @; 


index = Mode-?eol * x + ¥; 


if (ret = VIOSCRLOCK(WAIT_LOCK, i* wait until in fore- 
ground */ 
(char far *)&e, 
O)) { 
printf(“\nVioSerLock failed; %d”,ret) ; 
DOSEXIT C1, 0): 


while (*e j= *\0") 
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buf [indext+] = MAKEUNSIGNED(*stt+,attrib); 


VIOSCRUNLOCK (0) ; 


main() 


unsigned far *buf; 
unsigned length; 


struct ModeData ModeData; 
struct PhysBufData PhysBuf; 


char s[80]; 
unsigned ret, i; 


els) % 

ModeData.length = sizeof(struct ModeData) ; 

if (ret = VIOGETMODE(&ModeData, 0)) { 
printf(“\nVioGetMode failed: %d”,ret); 
DOSEXIT{(1,0) : 


if (ModeData.type & NON_MONO) 

PhysBuf.buf_start = 0xB8000; /* CGA address */ 
else 

PhysBuf.buf_start = 0xBO000; /* MDA address */ 


/* for graphics mode, the buffer can be up to 64K for an 
EGA* / 
/* and 16K for CGA */ 


PhysBur.buf_leneth = (25 * 80 *2)3/* length of the video 
buffer */ 
/* for text mode */ 


if (ret = VIOGETPHYSBUF((struct PhysBufData far *)&PhysBuf, 
O)) { 
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printf(“\nVioGetPhysBuf failed: %d”,ret); 
DOSEXIT(1,0); 


FP SEG(buf) PhysBuf.selectors [0]; 


/* make long pointer to ses */ 


FP_OFF (buf) 0; 


WriteBuf (“Example of writing to physical buf”, 


Bs /* cow x col coordinate */ 
but, {/* Buffer pointer */ 
&ModeData, 

(char)NORMAL) ; 


DOSEXIT(1,O) + 


Screen Saving and Restoring Techniques 


An application that directly manipulates the physical video buffer must directly 
concern itself with the actions of other applications within the system. Because 
such an application directly manipulates the physical video buffer, the operating 
system does not maintain a logical video buffer for it. When such an application 
is switched into the background, or if a pop-up is issued by a background process, 
the information in the physical video buffer will be lost or compromised. In order 
to preserve its screen image, any application that directly accesses the physical 
video buffer must make a copy of the contents of the physical video buffer 
whenever it is switched from the foreground, or interrupted by a pop-up. When 
this application is switched back into the foreground it must restore the PVB with 
the previous screen image. 

OS/2 provides functions that allowa graphics mode application which manipu- 
lates the video board‘ to implement screen saving and restoring techniques during 
these events: 


# Session switching by the user. 


“For the rest of the chapter we will refer to such an application as a graphics mode application. 
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= Another foreground session is initiated by an application with DosStartSes- 
sion. 

= A session is switched to the foreground by the application with DosSe- 
lectSession. 


" A background application or OS/2 requests to pop-up with VioPopUp or 
to release control with VioEndPopUp. 


A text mode application, or a graphics mode application that uses the functions 
provided by the PM, does not have to concern itself with saving and restoring the 
screen contents unless it directly modifies the physical display buffer or the 


VioSaveRedraw Thread Graphics Mode 
saves an image of Process moving 


physical video display : into 
buffer (PVB) in memory background 


Background | “losaveReDraw Foreground 


Thread 


S VioSaveRedraw Thread 
ame Process restores the contents 


later of the PVB with the 
moving into = image it had pre- 


foreground viously saved in 
memory 





Figure 16.2 VioSaveReDraw Thread 
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registers of the video adapter. OS/2 automatically saves and restores the screen 
and video mode settings for such applications. 

There is a problem when switching between EGA text mode and graphics mode 
applications. The EGA registers can only be written to, and notread. Ifa text-based 
application within a session sets the screen attributes, and a graphics-based 
application which directly manipulates the attribute registers is switched to the 
foreground, when the text-based session is switched back, OS/2 1s unable to restore 
the previous screen attributes and will simply assume the default attributes for the 
video adapter. For exampie, if a text-based session changes the color of the screen, 
and a graphics application which modifies the registers of the adapter is switched 
to the foreground, when the text-based session is switched back, the screen will no 
longer have the specified color. 

Graphics mode applications must either use VioSavReDrawWait or VioMode- 
Wait to in order to determine when to save or restore the screen. The function 
. VioSavReDrawWait informs a session whether it is being switched into the back- 
ground, or the foreground. When the session is switched to the background, it 
must save the contents of its video buffer; when it is switched into the foreground, 
it must restore the contents of the buffer. The function VioModeWait informs a 
session that a pop-up application has released control of the screen. This allows 
a graphics mode application to reset the video mode of the adapter which was 
switched to text mode by the pop-up. No notification is provided when a 
background application requests a video pop-up. 

A graphics mode application should dedicate one asynchronous thread to 
perform the screen save and restore. This thread simply issues VioSavReDrawWait 
and waits for a session switch. VioSavReDrawWait returns a parameter which 
indicates to the thread whether it should save or restore the screen. ‘The 
VioSavReDrawWait thread checks this value and either writes the contents of the 
PVB toa private buffer or restores the contents of the screen, the display mode, and 
the state of the video adapter, as well as any other information necessary to redraw 
the screen. After completing the restore or save operation, the thread simply issues 
VioSavReDrawWait again to wait for the next session switch. To cancel the 
VioSavReDrawWait thread, another thread within the same process can issue 
VioSavReDrawUndo. 

When it is saving or restoring the screen, the VioSavReDrawWait thread is in a 
transition phase between foreground and background. The Session Manager, 
however, considers the session to which it belongs to be in the background. For 
this reason, the VioSaveReDrawWait thread should not issue VioScrLock or 
VioScrUnLock. 
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The VioSavReDrawWait thread should be in a loop that either saves or restores 
the contents of the screen and then reissues the function to wait for the next session 
switch. To prevent the system from hanging during its execution, it should not 
access the file system or request any API functions that might cause a hard error. 

The programmer should be aware that the Session Manager may notify the 
VioSaveReDrawWait thread to restore the screen before it has saved it. This will 
happen when a session is launched in the background and brought to the 
foreground for the first time. To prevent this, the application should either wait 
until it is in the foreground to start the VioSaveReDrawWait thread, or it should 
maintain a static variable to insure that a save has been performed before any 
restore is attempted. 

If the graphics mode application does not directly modify the registers of the 
video adapter, it does not need to dedicate a separate asynchronous VioModeWait 
thread to restore the video mode after a background pop-up. This is because OS/ 
2 saves and restores the contents of the physical buffer before and after a 
background pop-up or hard error processing. Even if the graphics application 
does manipulate the registers of the video adapter, the VioModeWait thread needs 
only to restore the video mode, the states of the video registers, and any other 
information needed to restore the state of the screen before the pop-up; it does not 
have to save and restore the screen image. If the application does not issue 
VioModeWait, OS/2 will restores the physical buffer and attempt to restore the 
video modes to the best of its ability when the pop-up is completed. To cancel the 
VioModeWait thread, another thread within the same process should issue 
VioModeUndo. 

The VioModeWait thread should restore the state of the video adapter and issue 
VioModeWait again to wait for the completion of the next pop-up. A VioModeWait 
thread should not try to access the file system, call any other API functions other 
than those it needs to restore the adapter attributes, or call any functions or 
dynamic link routines that request API functions. This is to prevent the system 
from hanging asa result of any errors generated by the API functions. For example, 
if the foreground thread of a graphics application generates a hard error, OS/2 
issuess a hard error processing background pop-up. When this pop-up terminates, 
the VioModeWait thread is instructed to restore the adapter’s video mode. If the 
VioModeWait thread attempts to access the file system not knowing that the hard 
error just occurred, it will cause the system to hang, requiring the user to cold-boot 
the system. 
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VioSavReDrawWait 


VioSavReDrawWait returns an indicator that informs a thread whether it 
should restore or save the screen image for the PVB. Only one process within one 
session can be dedicated to handle VioSavReDrawWait. Ifa thread in another 
process within the session attempts to issue VioSavReDrawWait it receives an error. 

VioSavReDrawWait expects three parameters, the video handle, the event 
indicator, and the type of notification requested. 

Not all applications need to save the contents of the screen when they are 
switched out of the foreground. This holds for applications that possess all the 
information required to regenerate the screen image at any time. Such applica- 
tions only need to redraw the screen image when moving into the foreground. 

The notification type, NotzfyT ype, is the value returned at the completion of the 
VioSavReDrawWait call. This value informs the thread whether a save or restore 
operation is required. 


VioSavReDrawWait (SavReDrawindic, NotifyType, VioHandle) 


unsigned SavReDrawIndic; /* event the thread wishes to be notified 
of */ 
unsigned far *NotifyType; /* save/restore operation */ 


unsigned VioHandle; /* reserved, must be zero */ 
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VioSavReDrawUndo 


VioSavReDrawUndo allows another thread to cancel the operation of the 
VioSavReDrawWait thread. This thread must belong to the same process as the 
thread which issued the VioSavReDrawWait call. The “undo” thread has the 
option of assuming ownership of the VioSaveReDrawWait capability. If ownership 
is reserved, the undo thread can call VioSaveReDrawWait without receiving any 
error. Ihe ownership option is specified by the variable, OwnerIndic. 

Also, the “undo” thread can determine whether the VioSavReDrawWait will 
return an error code or be terminated if it causes an error. This option is specified 
by KillIndic. | 


VioSavReDrawUndo (Ownerindic, Killlndic, VioHandle) 


unsigned OwnerlIndic; /* ownership option*/ 
unsigned KillIndic; /* thread termination option */ 


unsigned VioHandle; /* reserved, must be zero */ 
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VioModeWait 


VioModeWait notifies a waiting thread to restore the video state, the mode, and 
the contents of the video adapter’s registers at the end of a background pop-up. 
Only one process within a session can be dedicated to handle VioModeWait. Ifa 
any other thread within any other process within the session attempts to issue 
VioModeWait it receives an error. 

VioModeWait expects three parameters: the video handle, the request type, 
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and the type of notification. The request type, RequestType, specifies the type of 
event the function will be waiting for. This version of OS/2 offers only one possible 
value: 0, indicating the end ofa pop-up. The notification type, NotzfyType, is a value 
returned by the function which informs the calling thread of the type of screen 
operation which is required of it. Currently, it also has only one possible value, 0, 
which specifies a restore operation. 


VioModeWait (RequestType, NotifyType, VioHandle) 


unsigned RequestType; /* event the thread wishes to be notified 
of */ 
unsigned far *NotifyType; /* save/restore operation */ 


unsigned VioHandle; /* reserved, must be zero */ 
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VioModeUndo 


VioModeUndo allows another thread to cancel the VioModeWait thread. This 
thread must belong to the same process that started the VioModeWait thread. The 
“undo” thread has the option to take charge of the VioModeWait capability. If 
ownership is reserved, the undo thread can call VioModeWait without receiving 
any error. The ownership option is specified by variable, OwnerIndic. 

Also, the “undo” thread can determine whether the VioModeWait thread 
returns an error code or terminated if it causes an error. This option is specified 
by KillIndic. 


VioModeUndo (Ownerlndic, Killlndic, VioHandle) 


unsigned OwnerIndic; /* ownership option*/ 


unsigned KillIndic; /* thread termination option */ 


unsigned VioHandle; /* reserved, must be zero */ 
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Font Control 


A font is the name given to the series of pels which creates the image of a 
character as it appears on the screen. For example, the letter “A”can be repre- 
sented by the pels described in Figure 16.3. 

Each character to be displayed on the screen is represented by a unique 
combination of pels. The set of fonts represents the total number of characters 
that can be displayed by the adapter in text mode. Fonts are located in a font table 
defined by the video adapter. There are two types: RAM font tables, and ROM font 
tables. ROM font tables contain the fonts supplied by the manufacturer of the 





Figure 16.3 Video Character Font 
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video board—usually the standard screen representation for the set of ASCII 
characters supported by the adapter. ROM font tables cannot be modified. 

RAM font tables are used by adapters to support downloadable fonts. An 
application can specify a font table according to the format recognized by the 
adapter and download the font table into the video memory of the adapter. The 
adapter then uses the on-screen character images defined by this font table instead 
of those defined by its ROM font table. Using a downloadable RAM font table an 
application can change the appearance of the characters appearing on the screen. 
For example, an italics “A” can be displayed instead of a regular “A” Only the EGA 
and VGA adapters support downloadable fonts. All adapters, CGA, EGA, and VGA 
provide ROM font tables. 

The function VioSetFont is used to download a RAM font table. VioGetFont 
returns the address of a RAM or ROM font table. The exact format of a font table 
depends on the type of adapter being used. The technical reference for each 
adapter should be consulted for their formats. 

Because downloading a RAM font to the adapter requires direct access to the 
adapter video memory, applications that use VioSetfont will not be able to run as 
windows within the Presentation Manager. They can, however, execute as separate 
screens. 


VioGetFont and VioSetFont 


Each adapter provides several sizes of character fonts. Font sizes are distin- 
guished by the number of rows and columns of pels per character (or characters 
per screen row and column). The following is a list of font sizes supported by each 
graphics board. Applications can switch among them using the functions Vio- 
GetFont and VioSetFont. 


Adapter Font Size 

CGA 8x 8,8x 14 (pels per row by pels per column) 
EGA 8x8,8x14,9x 14 

VGA 8x8,8x14,9x 14,9x 16 


VioGetFont and VioSetFont both expect two parameters, video handle (which 
is reserved and does not need to be specified), and a pointer to a request block. 
The request block contains information which specifies the type of font to request 
and the address of a font table. VioGetFont returns the address of the font table 
specified by the request block. VioSetFont uses the information in the request 
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block to download a new font table to the adapter. VioSetFont is only supported 
for VGA and EGA boards. 
The request block must have the following structure: 


struct VIOCFONT { 


unsigned length; /* length of the request 
block in number of bytes 
ee 

unsigned req_type; /* request type */ 

unsigned pel_cols; /* number of pels per column 
a 

unsigned pel_rows; /* number of pels per row */ 

long font_data; /* pointer to font table “7 

unsigned font_len; /* length of the font table 


in number of bytes */ 


Length specifies the length of the request block in number of bytes. For this 
version of OS/2, the length is 14 bytes. 

Req_type specifies the type of font table to be retrieved for VioGetFont, (1.e., 
RAM font or ROM font). For VioSetFont, the value of reg_type can only specify a 
RAM font table since only RAM font tables can be changed. 

The values of pel_colsand pel_rowsrepresents the number of pels per column and 
per row (per character). Ihe combination of these values specifies the type of font 
whose font table location is being queried, or which is to be downloaded. These 
values must correspond to actual font sizes supported by an adapter. 

For VioSetFont, the pointer fonit_datarepresents the starting address of the font 
table to be downloaded and /font_len specifies the length of the table. 

For VioGetFont, the pointer font_data can have two possible values. If the 
application set the pointer to NULL, OS/2 returns the actual RAM or ROM 
address of the font table. The application can also instruct OS/2 to load the 
contents of the font table into an internal buffer provided by the application. The 
starting address of this buffer is then specified by the pointer font_data. Similiarly 
the length of this buffer is specified by font_len. 


VioSetFont (RequestBlock, VioHandle) 


VioGetFont (RequestBlock, VioHandle) 
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struct VIOFONT *RequestBlock; /* request block */ 


unsigned VioHandle; /* reserved and must be zero */ 





A Few Tips for Using Video Functions 


Several simultaneous VIO calls made by any process or thread can be active 
within a session. These calls are automatically serialized and synchronized by the 
video subsystem through the use of an internal semaphore. There are, however, 
several possible problems that the programmer should be aware of. 

A VIO function call within a critical section will fail if another thread within the 
same process had been blocked by this critical section during the middle of a VIO 
call. 

If a pop-up thread requests a semaphore or a system service during its pop-up 
session, and this resource is owned by another process within its screen group, the 
request for the semaphore or system resource will fail. Such a request will also fail 
if the requested resource is owned by the process that has been interrupted by the 
pop-up. In addition, if the pop-up thread interrupts the foreground session in the 
middle of a VIO call, the pop-up thread will not be able to issue a VIO call. 
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Advanced Device I/O 
Functions 


Installing Your Own Device Subsystem 


S/2 allows application programs to replace a function provided by a device 
C) subsytem with one of its own. This capability is necessary, for example, if 

an application must interface with a device not supported by OS/2. Asa 
worst case example, a manufacturer has produced a nifty little video adapter, one 
that leaves the VGA in the dust when it comes to performance. The manufacturer 
needs to insure that OS/2 programs can automatically use this card without any 
need for modification. To accomplish this, the manufacturer must provide a 
device driver so OS/2 can recognize the device. This device driver has to provide 
IOCTL routines which make up the video routines used by applications to access 
the device driver. Finally, all the old VIO calls have to be intercepted and replaced 
with those provided to access the new device driver. In this situation the manufac- 
turer has to provice a complete video subsystem to replace the one supplied by 
OB) 2: 

The above example represents the worst case. It is possible that this card might 
work with an existing OS/2 video device driver. Or, perhaps only a few VIO 
functions need to be replaced. In this case it is not necessary to replace the entire 
vidio subsystem. Applications can intercept VIO, MOU, and KBD calls and replace 
them with routimes of their own specification. The functions VioRegister, KbdReg- 
ister, and MouRegister allow a process to replace one or many VIO, KBD, and 
MOU functions respectively. 

The Presentation Manager uses these replacement capabilities to intercept all 
VIO, KBD, and MOU calls made by any applications running under it. Essentially, 
the PM substitutes its own API for that provided by OS/2. The extended API 
provided by the PM duplicates most of the functionality of the OS/2 API. This 
allows text based OS/2 applications to run under the PM without modification, 
and provides the additional synchronization needed to have several applications 
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within the same screen group access the mouse, keyboard, and screen. 

These register functions, however, are only effective in the session where the 
function is called. If another session is created, the default base device subsystem 
is used until one of the register functions is issued. In the above example of the 
nifty video adapter, to provide a transparent interface for OS/2 programs, each 
new session would have to run a small program to register the appropriate VIO, 
KBD, or MOU functions that replace those in the base video subsystem before any 
application coul be started in the screen group. Each replacement function must 
be implemented as a dynamic link routine, in the same way as the device subsystem 
functions provided by OS/2. 


The Problem of Serialization 


As you will see, the functions which allow parts or even the whole video 
subsystem to be replaced are easy enough to implement. But once this has been 
accomplished, an application must deal with matters that were previously the 
concern of the base device subsystem. Every time an application replaces a 
function from a device subsystem with one of its own, it must also assume the 
responsibility for providing any synchronization needed to share that function 
among the multiple threads within its session. Certain device drivers do not make 
provisions to handle more than one function request ata time. For example, if an 
application replaces the KbdStringIn function but provides no serialization 
mechanism, and two threads within the affected screen group both issue the new 
KbdStringIn at once, the device driver has no way to serialize (line up) these 
requests and may be corrupted by such simultaneous access. This serialization of 
function calls is usually handled by part of the base subsystem called the router. 

An application that replaces an API function which is targeted at a device driver 
that would be compromised by allowing multiple simultaneous calls to that 
function within the same screen group, will have to take steps to protect that 
function as it would any serially reusable resource or SRR (see Chapter 3). If an 
application replaces an entire device subsystem, it has to provide serialization 
mechanisms for any functions within that subsystem that require it. 

One method for providing the mutual exclusion required to serialize access to 
a device subsystem function is to associate it with a semaphore. This is done by 
allowing a thread to call the function only if the semaphore associated with it 1s 
clear (meaning that no other thread has issued it). Any other threads who have 
made the same function request will simply wait in the dispatch queue until the 
semaphore has been cleared. The keyboard subsystem provides a facility that 
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serializes access to the keyboard for multiple threads and processes within the same 
screen group by associating a semaphore with each function. Any application that 
wishes to provide similar serialization for the video or mouse subsystem will have 
to implement a similar mechanism. This facility is discussed at the end of the 
chapter. 


Replacing Video Subsystem Functions 


VioRegister replaces VIO functions. VioRegister is only effective for the screen 
group within which the function was issued. The function replaces VIO calls for 
every process within its screen group, but it has no effect on other screen groups. 
Whenever a registered VIO function is called by a thread within the session for 
which it was registered, its replacement routine will be called instead. ‘This 
replacement routine, however, can still call the default VIO function which it 
replaces. 

As explained in the previous chapter, a replacement VIO function is not called 
when the foreground session is interrupted by a pop-up background process. The 
default VIO function is used instead. It should also be noted that VioRegister has 
no effect if itis made by an application running as a background process which was 
started by an OS/2 detach command or with DosExecPgm. 

VioRegister is useful when an application needs to handle its own print-screen 
operations in response to the user pressing the PrtScr key. Normally the Session 
Manager traps the PrtScr key. Whenever it is pressed, the Session Manager issues 
VioPrtSc which sends a text screen image to the printer. ‘This function can only be 
called by the Session Manager. VioPrtScToggle is another function which can only 
be used by the Session Manager. VioPrtScToggle is called when the user presses 
Ctrl-P to toggle a continuous print screen operation. An application, however, can 
replace the VioPrtSc or VioPrtScToggle routines with its own calls within a session. 
Replacing these functions allows the application to handle the print screen or 
print toggle functions. For example, the default print screen function will not work 
for a graphics mode application. By trapping the VioPrtSc call, an application can 
try to provide the print-screen capability on its own. The new VioPrtSc routine can 
do whatever it wants. It can simply print something to the screen to notify the user 
that screen printing is not possible in graphics mode, or save the screen contents 
to a file. 

VioRegister remains effective within a session until any thread within the same 
process that issued it issues VioDeRegister. VioDeRegister deactivates all VIO 
replacement routines previously registered within the session. There are no 
facilities that allow for the selective deactivation of VIO functions. 
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VioRegister 


VioRegister expects the following parameters: an indication of the VIO func- 
tion that is being replaced, the name of the dynamic link module where the 
replacement routine resides, and the entry point name for the replacement 
routine within the dynamic link module. The VIO function being replaced is 
specified by setting a bit in one of the two parameters FunctionMaskI and 
FunctionMask2. Only one VIO function at a time can be registered with these bit 
mask values, and only one replacement routine can be specified with the other 
parameters for the function. This means that VioRegister has to be called once for 
each VIO API routine that is being replaced. 

The meanings of each bit for FunctionMask 1 are as follows (remember only one 
bit in both parameters can be set per call): 
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The meanings of each bit of FunctionMask2 are: 





All replacement functions must be dynamic link routines. ‘Two parameters 
identify the entry point. ModuleName is a pointer to an ASCIIZ string containing 
the dynamic link module name where the dynamic link routine can be found. 
EntryPoint is a pointer to an ASCIIZ string containing the entry point name of the 
dynamic link routine which receives control when a registered function is called. 
This entry point name corresponds to the name specified in the EXPORTS 
statement of the dynamic link libraries module definition file. If the EXPORTS 
includes the ordinal option, then the entry point may be specified as an ordinal. 
The maximum length for ModuleName is 129 bytes and for EntryPoznt is 33 bytes. 

Registering a function is the same thing as telling OS/2 to use a different 
dynamic link routine than the one provided by the video subsytem. OS/2 uses 
ModuleName to locate the new dynamic link library, and EntryPoint to locate the 
entry point of the new routine within the dynamic link library. 

When the replacement function receives control, the values described in Table 
17.1 are automatically stored on its stack. 
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Stack Parameter Number of Bytes 

Parameters of the Function 1 -n (depending on the function) 

Normal VIO Far Call 4-bytes (long or DWORD) 

Function Number Replaced 2 bytes (unsigned or WORD) 

Entry Point in VIO Router 2 bytes (unsigned or WORD) 
(near entry point) 

Caller’s DS Value 2 bytes (unsigned or DWORD) 

FAR Return Address 4 bytes (unsigned or DWORD) 


Table 17.1 Stack Parameter Values 


The FAR return address must be used by the replacement function to return 
control to OS/2. The replacement function can go on to call the default VIO 
routine by returning control with the AX register loaded with a value of -1. IfAX 
contains any other value, this value will be returned to the application. The 
dynamic link routine should return a zero (0) if there is no error, and any other 
value should represent an error code. ‘The dynamic link function should use the 
standard OS/2 error codes whenever they are applicable. When the replacement 
video function returns control to OS/2, it should leave the stack just as it found it. 

The function number is just an index value defined by OS/2 to identify the 
replaced VIO function. The list of function numbers and the VIO functions which 
they represent are shown in Table 17.2. 


Function Number VIO Functions 
VioGetPhysBuf 
VioGetBuf 
VioGetShowBuf 
VioGetCurPos 
VioGetGetCurType 
VioGetMode 
VioSetCurPos 
VioSetCurType 
VioSetMode 
VioReadCharStr 


O ON ®D OF BP OF YO KF CO 


(continued) 
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10 
1] 
lz 
13 
14 
id 
16 
17 
18 
19 
20 
21 
22 
23 
24 
ao 
26 
Zi 
28 
ae, 
30 
31 
32 
33 
34 
35 
36 
37 
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VioReadCellStr 
VioWrtNChar 
VioWrtNAttr 
VioWrtNCell 
VioWrt TTY 
VioWrtCharStr 
VioWrtCharStrAtt 
VioWrtCellStr 
VioScrollUp 
VioSCrollDn 
VioScrollLf 
VioScrollRt 
VioScrollDn 
VioGetAnsi 
VioPrtSc 
VioScrLock 
VioScrUnLock 
VioSavReDrawWait 
VioSavReDrawUndo 
VioPopUp 
ViokndPopUp 


' VioPrtScToggle 


VioModeWait 
VioModeUndo 
VioGetFont 
VioGetConfig 
VioSetCp 
VioGetCp 


(continued) 
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38 VioSetFont 
39 VioGetState 
40 VioSetState 


Table 17.2 Function numbers and VIO functions they represent 


VioRegister (ModuleName, EntryPoint, FunctionMask1, FunctionMask2) 


char far *ModuleName; /* name of dynamic link library */ 
char far *EntryPoint; /* name of dynamic link routine */ 
long FunctionMask]1; /* function mask number | */ 


long FunctionMask2; /* function mask number 2 */ 
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VioDeRegister 


VioDeRegister deactivates all the replacement VIO functions for the session 
previously registered with VioRegister. All VIO calls within the session will now use 
the standard video subsystem. VioDeRegister must be called by the same process 
that issued VioRegister. 


VioDeRegister() 


/* there are no arguments for this function */ 


Example 
Make File—PRTSC 


CFLAGS=-Asnu -Zi -Lp -Gzs -Od # -Zi for use with CodeView 


VLODrtse.cb]: Vleprrec.e¢ 
el -e S({CFLAGS) vioprtsc.c 


prtec.dils: yvieprtec.ob7 
link /eo vioprise .prtsc.dll,,dosealls,1ib, prtsc.def 


pttsec. lib: prise.der 
implib prtec.lib prtse.der 


vioreg.obj: vioreg.c 
el -¢ -2Zi -Lp “GZe -Od vaored,.© 


vioreg.exe: vioreg.obj 
link feo viores,vioreg,,doscalls.1iib: 
DEF File - PRTSC.DEF (Definition file for DLL) 


; Example of Module definition file for the DLL program 


LIBRARY PRTSC stell the linker that the program 
<6 @ DOL 


PROTMODE srun only in protected mode 
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DESCRIPTION ‘VIOPRTSC replacement’ ;This string will be 
;imbedded into the 
;dynamic library file 


DATA SHARED ‘ trake the default to share 
data segments 


SEGMENTS 

_DATA CLASS ‘FAR_DATA’ NONSHARED 
_BBS CLASS ‘FAR_DATA’ NONSHARED 
CONST CLASS ‘FAR_DATA’ NONSHARED 


EXPORTS ;sExports routines. 
VIOPRTSC @l 
Source Program—VIOPRISC.C (DLL function) 


/* thie program is the DLL function replacing the VioPrrSer 
FunekiLon. 


This routine simply captures what’s on the screen and writes it 
to a file called PRINTER.IMG 


ad | 
include “doscalls.h” 


extern unsigned far pascal VIOREADCHARSTR ( 


char far *, /* Character Buifer *¥ 
iieienéed tar *, /* Length of siting */ 
unsigned, f= row */ 

unsigned, ce eek. Fe 

unsigned ); /* Wie Handles *7 


extern unsigned far pascal VIOWRTCHARSTR ( 


char far *; /* Seine te be weltien *y 
unsigned, J* Length or string */ 
unsigned, fo pie: Ff 

unsigned, fe eel: Sy 


unsigned ); /* Vio Handle */ 
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#define O_FAIL 0x0000 /* eonstant for DosOpen */ 
4tdefine O OPEN 0x0001 

tt}define O REPLACE 0x0002 

+#define O CREAT 0x0010 /* ereate if File not existe */ 
ffdefine DENY_READ 0x0010 /* gharine mode */ 


ttdefine DENY WRITE 0x0020 
ft}define DENY NONE 0x0040 


4#Kdefine READ ONLY 0x0000 /* access mode */ 
}tdefine WRITE ONLY 0x0001 
}tdefine READ WRITE 0x0002 


char _FileName[] = “PRINTER.IMG”:; 
int far edeécl ._aertused() 1} 


i* Thies i¢ the start-up fetitine aid must return a O er 1. Ad 
means successful 


of 


int far cdeacl  astartid { 
return iL * 


/* every register function should be declared as the following 
to receive the parameters passed to it. 


a 


void far pascal VIOPRTSC() 
{ 
Static char sereen[|2001]: /* total chars on screen */ 
/* we need to make this static */ 
/* otherwise this variable */ 
/* would have to come off the stack */ 
/* @£€ the ealler’s routine *; 
unsigned length; 
unsigned fd, ActionTaken, Written, ret; 


length = 2000; /* read the entire screen */ 
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ret = VIOREADCHARSTR((char far *)screen, 
(unsigned far *)&length, 


(', /* row & column */ 
O, 
0); 
i¢ (rat) { 
return; 


i” @pen the fale. */ 

ret = DOSOPEN((char far *)_ FileName, 
(unsigned far *)é&fd, 
(unsigned far *)&ActionTaken, 


OL, /* N/A WHEN OPEN AN EXISTING FILE */ 
0, /* game as above */ 
O_OPEN | O_CREAT, 
DENY_NONE | READ_WRITE, /* open mode 
OL) ; 
if (ret) { 
recurn 


/* write sereen to file */ 
ret = DOSWRITE(fd, (char far *)screen, (long) length, 
&Written) ; 
DOSCLOSE (id) ; 
return; 


} 
Source Program—VIOREG.C (Test Program) 


/* VIOREG.C 


This program demonstrates how to use VIOREGISTER. It will 
replace the function VIOPRTSC with its own DLL function. 


stead of calling VIOPRTSC whenever the shift-PrntScrn key is 
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re 


In= 


hat, 05/2 will call the substituted DLL routine VIOPRTSC, which 


will save the contents of the screen to a file called 
“PRINTER.IMG”. 


ey 


include “doscalls.h” 


694 Advanced Programmer's Guide to OS/2 


include “subcalls.h” 


+#define MODULE “PRT SC” 
4tdefine ENTRY “VIOPRTSC” 


define VERT 
+#define HORZ 
#tdefine UPRT 
define LWLF 
define LWRT 
+#define UPLF 


/* definition for drawing box */ 


Mm PW NY F OO 


void WriteScreen(s,x,y) /* write date to screen */ 
ghar "a: 
unsigned x,y; 
{ 
VIOWRTCHARSTR(s,strilen(s), x,y, 0); 


woid box(x,y,*1,¥1) /* draw box */ 
unsigned x.y.x1.yl: 


{ 
static char border|[6] ={ *\xB3’,*\xG4',*\xBF’,’\5C0'.° \xD9', 
“heDA” | s 


int i: 
int row, column: 


VIOGETCURPOS (&row, &column,0O); 


VIOWRTNCHAR (&border [HORZ] , (yl-y-1),x,yt1,0); 
VIOWRTNCHAR (&border [HORZ] , (yl-y-1),xl,ytl1,0); 


for (i=wtl:4 < wleadt) f 
VIOWRTNCHAR (&border [VERT] ,1,i,y,0); 
VIOWRTNCHAR (&border[VERT],1,i,y1,0); 

} 

VIOWRTNCHAR (&border[UPRT],1,x,yl1,0); 

VIOWRTNCHAR (&border[LWRT],1,xl,y1,0); 

VIOWRTNCHAR (&border[UPLF],1,x,y,0); 
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VIOWRTNCHAR (&border [LWLF],1,xl,y,0); 

VIOSETCURPOS (row, column,0O): /* move the cursor back to */ 
/* otiginal position */ 

main() 


unsigned ret; 
long maskl, mask2; 


ehar e[2| 

e{o| = * *s /* eall toe replicate is a blank */ 
c[l] = 7; /* with normal attributes */ 

maskl = 0x01000000; /* turn the VIOPRTSC bit on */ 


ret = VIOREGISTER ((char far *)MODULE, 
(ehar far *)ENTRY, 
maski, mask2): 
if (fet) { 
printf (“\nVioRegister failed: %d”,ret); 
DOSE. LT tL, Oss 


/* @lears the box area */ 
VIOSCROLLUP(3,8.7,.57,4,. Cehar far *)je,0) 
Box(3.6, 7257) /* draw a box */ 


WriteScreen(“PRESS SHIFT-PRINT SCREEN to test the pro- 
gram.” s 
55 10); 


DOSSLEEP ( (long) 5000) ; (* wait ror 5 seconds */ 


VIODEREGISTER(); 
DOSEXTYT (1,0). 
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Replacing Keyboard Subsystem Functions 


KbdRegister replaces KBDxxx functions provided by the keyboard subsystem. 
KbdRegister is only effective for the screen group in which the function is issued. 
All processes within the screen group are affected by the call, but it has no effect 
within other screen groups. Whenever a registered KBD function is called by any 
thread within the session, a designated replacement routine will be executed 
instead. ‘This replacement routine, however, can still call the default KBD 
function. 

The programmer should be aware of the fact that KbdRegister is not effective 
when itis called bya detached process started by an OS/2 detach command or with 
the function DosExecPgm. 

KbdRegister remains effective within a session until KbdDeRegister is called by 
any thread within the same process that issued KbdRegister. KbdDeRegister 
deactivates all KBD replacements routines previously registered within the session. 
There are no provisions for selectively deactivating replacement KBD functions. 


KbdRegister 


KbdRegister expects the following parameters: an indication of the KBD 
function being replaced, the name of the dynamic link module where the 
replacement routine resides, and the entry point name for the replacement 
routine within the dynamic link module. The KBD function being replaced is 
specified by setting the appropriate bit in the bit-mask value parameter Function- 
Mask. Only one replacement routine and one routine to be replaced can be 
specified per KbdRegister call. 

The meaning for each bit of FunctzonMask is as follows: 
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All replacement functions must be dynamic link routines. Two parameters 
identify the entry point. ModuleNameis a pointer to an ASCIIZ string containing the 
dynamic link module name where the dynamic link routine can be found. 
EntryPoint is a pointer to an ASCIIZ string containing the entry point name of the 
dynamic link routine which receives control when a registered function is called. 
This entry point name corresponds to the name specified in the EXPORTS 
statement of the dynamic link libraries module definition file. If the EXPORTS 
includes the ordinal option, then the entry point may be specified as an ordinal. 
The maximum length for ModuleName is 129 bytes and for EntryPoznt is 33 bytes. 

Registering a function is the same thing as telling OS/2 to use a different 
dynamic link routine than the one provided by the video subsytem. OS/2 uses 
ModuleName to locate the new dynamic link library, and EntryPoint to locate the 
entry point of the new routine within the dynamic link library. 

When the replacement function receives control, the values in Table 17.3 are 
automatically stored on its stack. 


Stack Parameter Number of Bytes 
Parameters of the Function 1 -n (depending on the function) 
Normal KBD Far Call 4 bytes (long or DWORD) 


Function Number Replaced 2 bytes (unsigned or WORD) 


(continued) 
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Entry Point in KBD Router 2 bytes (unsigned or WORD) 
(near entry point) 

Caller’s DS Value 2 bytes (unsigned or DWORD) 

Far Return Address 4 bytes (unsigned or DWORD) 


Table 17.3 Stack Parameter Values 


The FAR return address must be used by the replacement function to return 
control to OS/2. The replacement function can go on to call the default KBD 
routine by returning control with the AX register loaded with a value of -1. If AX 
contains any other value, this value will be returned to the application. The 
dynamic link routine should return a zero (0) if there is no error, and any other 
value should represent an error code. The dynamic link function should use the 
standard OS/2 error codes whenever they are applicable. When the replacement 
keyboard function returns control to OS/2, it should leave the stack just as it found 
it. 

The function number is just an index value which identifies the KBD function 
that was replaced. The function number is the same as the numerical position of 
each bit in FunctionMask (1.e., function KBDOpen is function number 5). 


KbdRegister (ModuleName, EntryPoint, FunctionMaskt1,) 


char far *ModuleName; /* name of dynamic link library */ 


char far *EntryPoint; /* name of dynamic link routine */ 


long Function Mask; /* function mask number */ 
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KbdDeRegister 


KbdDeRegister deactivates all the replacement KBD functions previously 
registered with KbdRegister for the session. All KBD calls within the session will 
now use the base keyboard subsystem. KbdDeRegister must be called by the same 
process that issued KbdRegister. 


KbdDeRegister() 


/* there are no arguments for this function */ 


Replacing Mouse Subsystem Functions 


Mouse API functions are replaced in the same way as keyboard API functions 
(all the same restrictions apply). We will not belabor the point by presenting a 
complete discussion of the replacement of mouse functions. We will merely 
present the pertinent information. Please refer to either of the preceding sections 
for a complete discussion of how a register function works. 

Moukegister specifies replacements for MOU API functions one at a time. 
MouRegister remains effective within the session until MouDeRegister is called by 
a thread within the same process. 


MouRegister 


Like KbdRegister, MouRegister expects a mouse function mask, a dynamic link 
module name, and an entry point for a routine within that module. The MOU 
functions are specified with FunctionMask. The parameter is a bit mask value with 
each bit representing one MOU function that can be registered. Only one MOU 
function can be replaced per call. 

The meanings of each bit for FunctionMask are as follows: 
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When the replacement function receives control, the values in Table 17.4 are 
placed on its stack. 


Stack Parameter Number of Bytes 

Parameters of the Function 1 -n (depending on the function) 

Normal MOU Far Call 4 bytes (long or DWORD) 

Function Number Replaced 2 bytes (unsigned or WORD) 

Entry Point in MOU Router 2 bytes (unsigned or WORD) 
(near entry point) 

Caller’s DS Value 2 bytes (unsigned or DWORD) 

Far Return Address 4 bytes (unsigned or DWORD) 


Table 17.4 Stack Parameter Values 


For an explanation of the meanings of all these values please refer to the 
corresponding section on KbdRegister. 


MouRegister (ModuleName, EntryPoint, FunctionMask) 


char far *ModuleName; /* name of dynamic link library */ 


char far *EntryPoint; /* name of dynamic link routine */ 


long Function Mask; /* function mask number */ 
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MouDeRegister 


MouDeRegister deactivates all the replacement MOU functions previously 
registered with MouRegister for the session. All MOU calls within the session now 
use the base mouse subsystem. MouDeRegister must be called by the same process 
that issued MouRegister. 


MouDeRegister() 


/* there are no arguments for this function */ 


Keyboard Manipulation Functions 


There are several keyboard functions which can be used by the Session Manager 
and the keyboard subsystem, but not by an application. We include a discussion 
of these functions because they help to illustrate how a device subsystem serializes 
calls made to the device driver. These functions are KbdSynch, KbdShellInit, and 
KbdSetFGND. 


KybdSync, KbdSetFgnd, and KbdShellinit 


KbdSync is called by the Session Manager to serialize access to the keyboard 
subsystem within each screen group. Before a KBD call is passed to the KBD 
subsystem, it is passed via KbdRegister to a router (a router is a redirection 
mechanism). Before being passed on to the KBD subsystem, a KBD call must first 
take control of a semaphore associated with the router. Once the KBD subsystem 
finishes servicing a call, it clears the semaphore so that the next call can be serviced. 
Each KBD call has a router and a semaphore associated with it. The router blocks 
access to any threads trying to make a call if the associated semaphore is set. In this 
way, serial access to the device driver is maintained. 

Because of the importance of KbdSync for serializing calls it should not be 
called by an application. If an application replaces a single API function, or the 
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entire subsystem by registering every API keyboard function, it has to deal with this 
issue to a certain extent. 

KbdSetFGND is used by the subsystem to raise the priority of one of the 
subsystem foreground threads that are accessing the keyboard. With a higher 
priority, this thread has faster I/O access to the keyboard. Remember this thread 
is one of the threads started by the keyboard subsystem, not a thread set up by the 
foreground session. 

KbdShellInit is called by the command shell to identify itself to the keyboard 
router. [his is necessary in order for the command shell to work with the keyboard 
subsystem. This call is issued when the shell is loaded by the Session Manager. 


KbdSync (lOWait) 


unsigned [OWait; /* wait option */ 








There are no arguments for KbdSetFgnd and KbdShellInit. 


Chapter 18 





Device I/O Control Functions 


supported device drivers for their associated device subsystems. A device 

subsystem translates an API instruction into its corresponding IOCTL call, 
and any information returned by the IOCTL function is back to the application. 
Most VIO functions are simply translated into a corresponding IOCTL call by the 
video subsystem. The same holds true for KBD and MOU functions and their 
respective subsystems. Several VIO, KBD, and MOU calls do not have any 
corresponding IOCTL functions. These are VioRegister, KbdRegister, MouReg- 
ister, and their deregister counterparts. 

A device subsystem does not merely translate the function calls it receives into 
IOCTL calls. Italso provides some of the synchronization required to allow several 
processes within one session to access the same device. Much of the synchroniza- 
tion, however, is done by the device driver. 

Even though almost every API function can be replaced with an IOCTL call, we 
recommend that the programmer use the API function. IOCTL functions should 
only be used for capabilities that are not provided by any of the API functions. One 
of the main reasons for this is that the IOCTL functions do not all share a uniform 
mechanism for returning error codes, while the API functions do. In addition the 
IOCTL functions are specified by a generic call. They are distinguished from one 
another only by their function and a category number. The lack of a mnemonic 
label for IOCTL functions makes the task of program coding and debugging more 
difficult. 

This chapter presents only those IOCTL functions which provide OS/2 appli- 
cations with capabilities above and beyond those provided by OS/2 API. These 
functions can be divided into five basic categories: 


[) evice I/O control (IOCTL) functions are provided by each of the OS/2 


= Functions that allow the keyboard to be manipulated 


= Functions that allow a logical disk drive to be manipulated at the sector level 
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= Functions that allow a physical disk drive to be manipulated at the sector 
level 


= Functions which allow the parallel port to be manipulated 
=" Functions that allow an asynchronous port to be manipulated. 


The most important are the IOCTL functions that manipulate the asynchro- 
nous port. All communication programs written for OS/2 standard edition have 
to make use of these functions. This is because OS/2 standard edition does not 
provide any API for asynchronous communication. Unfortunately, due to limita- 
tions on the scope of this book we will be unable to launch a sustained discussion 
of the issues involved in asynchronous communication. We will merely list each 
function along with a short disussion of its use, for the benefit of the programmer 
who already understands the issues involved in writing communications programs. 
The parallel port functions allow a parallel port and printer to be configured and 
controlled in ways that are impossible using standard API. But perhaps the most 
glamorous IOCTL functions are those which allow the logical and physical drives 
to be directly manipulated. These allow for the development of programs with 
capabilities like the famed Norton Utilities. 

In this chapter we will first discuss the syntax of the generic [OCT L function call. 
This will be followed by a discussion of several keyboard functions. Then we will 
learn how to perform direct I/O access to the logical and physical drives, and how 
to manipulate the parallel printer port and an asynchronous port. 


DosDeviOCTL 


The function DosDevIOCTL must be used to issue an IOCTL function. [OCTL 
functions are identified by category and function number. For example, serial 
IOCTL functions belong to category 1, and keyboard IOCTL functions belong to 
category 4. Within each category, functions are identified by a function number. 
To issue an IOCTL function, both the category number and the function number 
of the desired function must be specified. 

A device handle which identifies an opened device is also required by DosDev- 
IOCTL. This device must have previously been opened with the function 
DosOpen which returns the device handle. The only exception is the device 
handle for a physical disk which must be obtained with DosPhysicalDisk. Table 
18.1 shows devices that are accessible through IOCTL functions. | 
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Name Device Supported 

LPT1 or PRN First parallel port or parallel printer 
LPI2Z+i213 Second or third parallel port 

COMI - COM3 Asynchronous communication port | to 3. 


These names are reserved only when the 
asynchronous support device drivers are 
loaded in the config.sys file. 


KBD$ Keyboard 

SCREEN$ Screen 

POINTER$ Pointer device (mouse screen support) 
MOUSE$ Mouse 

A: - 2: Drive names for logical drives A to Z 


Table 18.1 Devices accessible through IOCTL functions. 


DosDevIOCTL also expects two pointers, Data and Parmlist. Data points to the 
memory block where the returned data will be stored. For some functions, 
especially I/O calls, this parameter is also used for passing information. ParmList 
points to the block containing the input parameters. The size and the format of 
the returned data block and the parameter block vary from function to function. 
If a function does not require any parameters and/or returns no data, then 
ParmListand/or Datamust also be NULL. Ifa function requires a NULL value, the 
calling thread must explicitly set this parameter to NULL. Ifa DosDevIOCTL call 
contains incorrect parameters, a general failure error code is returned. Error 
codes returned by this function in the range of FEOO to FEFF are device driver 
dependent values. The error code returned in the range of FF00 to FFFF are user 
dependent error codes. 

What follows is the general syntax for an IOCTL function call and their 
compatability mode restrictions. The remainder of this chapter presents the 
functions individually. The following information is presented for each IOCTL 
function: a category number, function number, an explanation of the function, 
the structure of the parameter list, and the structure of the returned data block. 


DosDevliOCti (Data, ParmList, Function, Category, DevHandle) 


char far “Data; /* pointer to the data block to be 
returned */ 
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char far *ParmList; /* pointer to the parameter lists */ 
unsigned Function; /* function number */ 

unsigned Category; /* category number */ 

unsigned DevHandle; /* device handle */ 





Compatibility Mode Restrictions 


The following restrictions are applied to DOS mode applications: 


"Category 1, functions 41H and 42H are supported. 
=" Categories 2, 3, and 4 are not supported. 
"Category 5, functions 42H, 44H, 46H, 62H, 64H, and 66H are supported. 


=" Categories 6 and 7 are not supported. 
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=" Category 8, functions 00H-03H, 20H, 21H, 43-45H, and 63H-65H are 
supported. 


=" Categories 9, 10, and 11 are not supported. 


Keyboard IOCTL Functions 


Keyboard IOCTL functions belong to category number 4. There are a great 
many keyboard IOCTL functions and most have a corresponding KBD API 
function. Therefore, only those IOCTL functions which provide services not 
provided by the standard OS/2 keyboard API are discussed. 

Function 54H specifies the keyboard typematic rate and delay rate. Function 
76H returns the Session Manager hot key sequences. Function 77H returns the 
keyboard type. These functions are not extremely useful to most applications, but 
they have been included for the curious. Before a keyboard IOCTL function can 
be issued, the keyboard must be opened with DosOpen to obtain the device 
handle. 


Set Typematic Rate and Delay: 54H 


Each key on the keyboard has the repeat key capability. The typematzc delayis the 
time that a key must be held down in order to generate the first repeat key signal. 
Typematic delay time is measured in milliseconds. The typematic rateis the number 
of characters a key generates per second. 

Both values have maximum values. Ifan application specifies a rate greater than 
the maximum, this maximum value is assumed. The maximum value for typematic 
delay is 50 milliseconds, and for typematic rate is 10 characters-per-second. 


int DosDeviOCtl (OL, PtrDelayStruc, 0x0054, 0x0004, Device_Handle) 


struct DelayRate far *PtrDelayStruc; 


unsigned DeviceHandle; 
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Data Block Format (Data): NULL 


Parameter List Format (ParmList): PtrDelayStruc 





or 


struct DelayRate { 
unsigned delay; 
unsigned rate; 


Determine Keyboard Type: 77H 


int DosDeviOCtl (PtrKbdStruc, OL, 0x0077, 0x0004, Device_Handle) 


struct KbdType far *PtrKbdStruc; 


unsigned DeviceHandle; 
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Data Block Format (Data): 





Or 


Struct KbdType { 
unsigned type; 
long reserved; 


Parameter List Format (ParmList): NULL 
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Get Session Manager Hot-Key: 76H 


Function 76H returns two kinds of information: the number of hot key 
sequences the keyboard device driver can support and a report of the hot key 
sequences the keyboard driver is currently set to handle. A hot key is a keystroke 
sequence previously defined by the Session Manager to obtain its attention. The 
Session Manager defines the hot key sequence using JOCTL function 56H 
whenever a screen group is brought into the foreground. For example, Alt-Esc 
usually defines a switch to the next foreground session, and Ctrl-Esc loads the 
program selector menu. 

A 6-byte data block is returned for each hot key sequence. If the current Session 
Manager has defined two hot key sequences, two such data blocks are returned. 
The application must prepare a data buffer large enough to store all hot key 
sequences that might be returned. To ensure that a large enough data buffer is 
specified to handle all the returned hot key sequences, first issue function 76H to 
determine the maximum number of hot key sequences supported by the device 
driver. The current keyboard driver can handle a maximum of 16 hot key 
sequences. The programmer should set up a buffer large enough to handle the 
maximum number of data blocks. 

The structure of the data block returned for each hot key sequence looks like: 


struct HotKeyBuf { 


unsigned HotKey; /* bit-mask value specifying 
the hot key */ 

char make_code; /* gean code for the het key 
make */ 

char break_code; /* scan code for the hot key 
break */ 

unsigned ID; /* hot key ID identifying it 


from the next one */ 


} 


For assembler programs, the same structure can be defined in the following 
manner: 


Field Length 
Hot key WORD 
Make Code BYTE 
Break Code BYTE 


Hot Key ID WORD 
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HotKey is a bit mask value which represents any meta-keys that are part of the hot 
key sequence. Each bit represents a meta-key. Ifa bit is set, then the key is part of 
the hot?key sequence. If two bits in the bit mask are set, both these keys must be 
pressed at the same time to generate the hot key. The following is a list of the 
meanings for each bit mask value for the HotKey field: 





The hot key JD differentiates one hot key sequence from another. The 
make_codeand break_code fields are used to specify one other key which can be part 
of the hot key sequence. The make_code field registers a key when it is pressed, and 
the breakcode registers a key when it is released. The two parameters are mutually 
exclusive—only one can appear. The full hot key sequence is determined by both 
the HotKey value and either make_code or break_code. For example, the hot key 
sequence Alt-Esc has the following values: 


make_code = 27 
Bit 9 of HotKey will be ON and the rest are OFF. 
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int DosDeviOCtl (PtrHotKeyBuf,InfoType , Ox0076, 0x0004, Device_Handle) 


struct HotKeyBuf far *PtrHotKeyBuf; 
unsigned far *InfoType; 


unsigned DeviceHandle; 





Data Block Format (Data): PtrHotKeyBuf 





Parameter List Format (ParmList): InfoType 





The possible values for this parameter are: 
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Logical Disk IOCTL Functions 


A hard disk can be partitioned into several logical drives. Logical dnve IOCTL 
functions allow an application to manipulate a logical disk drive whether the 
physical drive is divided into several disk drives or not. A logical drive is opened 
by DosOpen, specifying the drive letter for the file name with the DASD Open bit 
set to indicate direct 1/O. DosOpen returns a device handle which is used with the 
DosDevIOCtl category 8 calls. A physical drive is opened with DosPhysicalDisk and 
the device handle returned must be used with IOCTL category 9 functions. 

Logical drive I[OCTL functions are used when an application needs to manipu- 
late the disk sectors at the logical drive level. For example, the OS/2 FORMAT 
program operates at the logical drive level, because it needs to format a logical 
drive that was partitioned from a hard disk. But the OS/2 program FDISK needs 
to operate at the physical drive level in order to partition a physical drive into 
several logical drives. 

When manipulating the disk sectors at the logical drive level, an application 
needs to know how the drive sectors are organized by OS/2. Each logical drive 
contains extra information used to organize the files and directories, a boot sector, 
2 FAT’, directory entries, and a volume label. In addition, the logical drive is 
divided into tracks with each track being made up of a variable number of sectors. 
A sector is 512 bytes long, and every two sectors require an FAT. 

This chapter does not not explain in detail how a logical disk is organized by 
OS/2. It suffices to say that this version of OS/2 organizes the logical drive in the 
same format as a DOS drive'. The next version of OS/2 will probably use a new 
logical drive format (for reasons discussed in the introduction to Chapter 11). We 


‘There are many reference books which provide this information, such as Peter Norton’s DOS Guide (Brady 
Books; New York). 
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only discuss the IOCTL functions that manipulate the logical drive at the sector 
level. These are very powerful functions. They have the ability to undelete a file, 
to recover lost data, and to provide all the capabilities for which The Norton 
Utilities are so renowned. The programmer should be certain to understand how 
the logical drive is organized before attempting to use these functions. 


Boot Sector (logical sector 0) 
FAT #1 
FAT #2 
Directory Entries 
Files Area 


Table 18.2 Format of a Logical Drive in this version of OS/2. 


Lock and Unlock Drive: OOH and 01H 


Locking a drive gives the calling process exclusive I/O access to it. Any other 
process trying to write to, or to read from, the drive at this time will not succeed. 
Locking the drive is necessary for issuing several IOCTL category 8 functions such 
as those that redetermine the drive media, format a track, write data to a track, etc. 
We must emphasize, however, that locking a drive excludes all other processes 
within the system from accessing the drive until it is unlocked. 

Under DOS, locking a drive does not cause any difficulties. Under OS/2 it 
might create a great deal of inconvenience if other running applications need 
access to the drive. This is one of the main reasons why category 8 [OCTL functions 
should only be used bya system program. The programmer should make sure that 
other processes do not interfere with the locking program’s operation. 

In some cases, it is better to lock a drive, perform all the necessary operations, 
then unlock it (instead of only locking it when it is explicitly required). This would 
be the case during the whole sequence of operations that format a drive. Locking 
the drive during the entire format procedure ensures that no other process can 
write to the drive during the formating process. The problems that the system 
might experience because of an undetected error during formatting far outweigh 
any privation undergone by the user or other applications during formatting. 

An interesting situation could arise if a program attempts to lock the logical 
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drive designated as the drive used for the segment swapping required to imple- 
ment virtual memory. This would cause a novel system crash. 

Functions 00H and 01H, respectively, lock and unlock the logical drive. A 
logical drive can only be locked if no other process has currently opened file 
handles on that drive or has opened the logical drive handle. The program should 
make sure that the locking operation was successful before continuing with other 
IOCTL functions. 


int DosDeviOCtl (OL, PtrCommand, 0x0000, 0x0008, Device_Handle) 


char far *PtrCommand; 


unsigned Device_Handle; 





Data Block Format (ParmList): NULL 





Parameter List Format (ParmList): PtrCommand 





int DosDeviOCtl (OL, PtrCommand, 0x0001, 0x0008, Device_Handle) 
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char far *PtrCommand; 


unsigned Device_Handle; 





Data Block Format (ParmList): NULL 





Parameter List Format (ParmList): PtrCommand 





Read, Write and Verify Track 


Function 44H writes data to a specified track. Function 64H reads data from a 
track. Function 65H verifies a track. None of these functions can be successfully 
called unless the logical disk drive has first been locked with function 00H. All 
three functions expect the same parameters. These I/O operations are performed 
on a specified number of sectors stored on a single track. The input parameters 
are: the head number, the cylinder number, the first sector number, the number 
of sectors, and the sector layout for all the sectors on the track where the read/ 
write/verify operation is done. A pointer to a data buffer must also be provided 
in the position occupied by the Data parameter. For the write operation, this data 
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buffer contains the data to be written, and for the read operation, the data buffer 
contains the returned data. 

The track layout table specifies the sector numbers on the track which are to be 
read/written or verified. The track layout table can contain sector specifications 
for as many sectors as can fit on a track. These sectors can be specified in non- 
consecutive order. For example, to write to sectors 1, 3, 2, and 5, the track layout 
can be specified in this non-consecutive manner. The track layout table will 
contain 4 WORD values containing the values 1, 3, 2, and 5. To read five sectors 
in consecutive order starting from 1, they should be specified in the track table in 
consecutive order. In this case, the track layout table must contain 5 WORD values 
in consecutive order starting with 1. In cases of non-consecutive sector layout, the 
read/write/verify operation is done one sector ata time. The first sector number 
is specified by the first WORD value of the track layout table. 

The programmer should recognize that the read IOCTL function cannot 
properly read a non-512-byte sector once a DMA violation error has been gener- 
ated. The application should first make sure that this error will not be generated 
or try to trap this error. 


int DosDeviOCtl (Buffer, PtrTrackStruc, 0x0044, 0x0008,Device_Handle) 
int DosDeviOCtl (Buffer, PtrTrackStruc, Ox0064, 0x0008,Device_Handle) 


int DosDeviOCtl (OL, PtrTrackStruc, 0x0065, 0x0008,Device_Handle) 


char far *Buffer; /* buffer containing data to be written or 
to store data read from disk */ 


struct Track far *PtrTrackStruc; 


unsigned Device_Handle; 
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Data Block Format (ParmList): Buffer 





Parameter List Format (ParmList): PtrTrackStruc 
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The track layout table must be in the following format: 


Field Length 

Sector number for sector 1 unsigned or WORD 
Size of sector 1] unsigned or WORD 
Sector number for sector 2 unsigned or WORD 
Size of sector 2 unsigned or WORD 
Sector number for sector n unsigned or WORD 


Size of sector n unsigned or WORD 
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In C, this structure is defined as: 


Serruct Track 4 


Ghar Command ; 

unsigned Head; 

unsigned Cylinder; 
unsigned Firstsector; 
unsigned Number of Sector; 
stiticet { 


unsigned SectorNumber; 
unsigned SectorSize; 
} TrackTable[N]; 


Set and Determine Logical Drive Parameters 


The ability to change the parameters for the logical drive is a very powerful tool. 
It should only be used when formatting the device driver. An application should 
not change the drive parameters on any other occasion. The drive parameters 
consist of the following information: the Bios Parameter Block (BPB), the number 
of cylinders defined for the drive, the device type, and the device attribute. 

Function 43H changes the logical drive parameters and function 63H deter- 
mines the current drive parameters. Function 63H can be used whenever 
necessary. Function 43H, as we have said, should be used with care. In order to 
change the drive parameters the drive must be locked. 


Function 43H (Change device parameters) 


The device driver maintains two separate BPBs for each drive: the current BPB 
which directly correlates with the media currently in the drive, and a recom- 
mended BPB which is based on the specifications of the physical drive. Both BPB’s 
usually contain the same values; but it’s also possible that the values may differ. For 
example, itis possible to use a 360K 5 1/4 inch diskette in a high density 5 1/4 inch 
drive. In order to allow the drive to manipulate the 360K diskette its BPB will have 
to be given the appropriatte values for a 360K diskette. In this case the recom- 
mended BPB would remain unchanged (though it is also possible to change this 
BPB). Once the BPB has been changed, all future media access by this device will 
be according to the current BPB. If, in our example, the disk drive needed to once 
again manipulate a high density diskette, it would have to reset the current BPB to 
the recommended values. 
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Function 43H has three options: change the recommended BPB of the physical 
device, change the current BPB of the media, or reset the current BPB to the 
recommended one. Changing the recommended BPB wipes out the values for the 
recommended BPB for the physical drive (its values have to be manually restored) 
and should be used with caution. Changing the current BPB governs future media 
access. 


int DosDeviOCtl (PtrBPB, PtrCommand, 0x0043, 0x0008,Device_Handle) 


struct BPB far *PtrBPB; 


char far *PtrCommand; 





Data Block Format (ParmList): PtrBPB 
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The structure of the extended BPB 1s as follows: 


Field 

Bytes Per Sector 

Sectors Per Cluster 
Number of Reserved sectors 
Number of FAT's 

Root Dir Entries 

Total Number of Sectors 
Media Descriptor 

Sectors Per FAT 

Sectors Per track 

Number of Heads 

Number of Hidden Sectors 
Large Total Sectors 


Reserved 


Length 

unsigned or WORD 
char or BYTE 
unsigned or WORD 
char or BYTE 
unsigned or WORD 
unsigned or WORD 
char or BYTE 
unsigned or WORD 
unsigned or WORD 
unsigned or WORD 
long or DWORD 
long or DWORD 

6 bytes 
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The possible values for device type are: 





In C, the above structure can be defined as: 


struct BPB { 


unsigned BytesPerSector; 
char sectorsPerCluster; 
unsigned TotalSector; 
ehar No_of_FAT; 
unsigned RootEntries; 
unsigned No_ of sector: 
char Media_Type:; 
unsigned SectorPerFAT; 
unsigned SectorPerTrack; 
unsigned No_of_Head; 
unsigned HiddenSector; 
unsigned LargeSector; 
unsigned No_of_Cylinder; 
char Device_Type; 


unsigned Device_Attribute; 
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Parameter List Format (ParmList): PtrCommand 





The possible values for the command information are: 





Function 63H (Determine device parameters) 


Function 63H has two options: return the recommended BPB for the drive or 
physical device or return the current BPB associated with the media actually in the 
drive. For more information about the different BPBs, please refer to the previous 
section. 


int DosDeviOCtl (PtrBPB, PtrCommand, 0x0063, 0x0008,Device_Handle) 


struct BPB far *PtrBPB; 


char far *PtrCommand; 





Data Block Format (ParmList): PtrBPB 
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Parameter List Format (ParmList): PtrCommand 
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The possible values for command information are: 





Format and Verify Track: 45H 


Function 45H formats and verifies a specified number of sector on a single track 
of a logical drive. The input parameters are: the head number, the cylinder 
number, the first sector number, the number of sectors, and the format track table 
which stores the sector layout for all the sectors on the track to be formated. The 
IOCTL function passes the format track table to the disk controller and the 
controller formats the track. 

On the track layout table, each sector to be formatted is described by a 4-byte 
value called a tuple. A tuple is a unit of information is usually schematized in the 
form (c, h, r,n), where c represents the cylinder number, h the head number, r 
the sector ID, andn the bytes per sector. The bytes per sector specified for all tuples 
on the format track table should be the same. This is because many controllers are 
unable to format a track with variable sector sizes. The possible values for 7 are: 
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Table 18.3 shows how the tuples are organized on the track layout table. 


C byte - cylinder number 
sector #1 h head - head number 
r byte - sector id 
n byte - sector size (bytes per 
sector) 
C byte - cylinder number 
sector #2 h head - head number 
r r - sector id 
n n - sector size (bytes per sector) 


Table 18.3 The organization of tuples on the track layout table. 


int DosDeviOCtl (OL, PtrTrackStruc, 0x0044, 0x0008,Device_Handle) 


struct Track far *PtrTrackStruc; 


unsigned far *Device_Handle; 





Parameter List Format (ParmList): PtrTrackStruc 


730 Advanced Programmer's Guide to OS/2 
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In C, this structure is defined as: 


struct Track { 


ehar Command ; 
unsigned Head; 
unsigned Cylinder; 
unsigned Pifstoector: 
unsigned Nimber of Sector: 
strict. { 

char cylinder; 

char head; 


Char eector ia: 
char sector size: 
) TrackTable|([N]: 


Physical Disk IOCTL Functions 


Physical drive IOCTL functions provide the most powerful disk I/O operations 
available under OS/2. These functions allow a system application to manipulate 
the entire physical drive at the track level regardless of the format of the drive. A 
physical drive is opened with DosPhysicalDisk and the device handle returned 
must be used with IOCTL category 9 functions. 


Lock and Unlock Drive: OOH and 01H 


Locking a drive allows the calling process to have exclusive I/O access to the 
physical drive. If the physical drive has been partitioned, then all the logical drives 
are also locked. Function 00H and 01H lock and unlock the physical drive, 
respectively. Locking a physical drive is only successful if no other processes have 
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opened file handles, or logical, or physical drive handles. A program should make 
sure that its locking operation was successful before continuing with other IOCTL 
category 9 functions. 


int DosDeviOCtl (OL, OL, OxO0000, 0x0009, Device_Handle) 


char far *PtrCommand; 


unsigned Device_Handle; 





Data Block Format (ParmList): 





Parameter List Format (ParmList): NULL 





int DosDeviOCtl (OL, OL, Ox0001, 0x0009, Device_Handle) 


char far *PtrCommand; 


unsigned Device_Handle; 
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Parameter List Format (ParmList): 





Data Block Format (ParmList): 





Read, Write and Verify Track: 44H, 64H and 65H 


Function 44H writes data to a specified track. Function 64H reads data froma 
track. Function 65H verifies a track. All three functions expect the same 
parameters as their category 8 counterparts. For a detailed explanation of these 
functions please refer to the discussion on page 718. 


Determine Physical Device Parameters: 63H 


Physical drive parameters consist of the following information: the number of 
cylinders and heads installed on the drive and the numbers of sectors which can 
fit on a track. Function 63H returns this data for the entire physical drive. 
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int DosDeviOCtl (PtrPhysBlock, PtrCommand, 0x0063, 0x00069, Device_Handle) 


struct PhysBlock far *PtrPhysBlock; 


char far *PtrCommand; 





Data Block Format (ParmList): PtrPhysBlock 
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Or 


struct PhysBlock | 
unsigned Reserved; 
unsigned Cylinder; 
unsigned Head; 
unsigned SectorPerTrack; 


unsigned 
unsigned 
unsigned 


reserved: 
reserved: 
reserved: 





unsigned reserved; 


PtrCommand 


Parameter List Format (ParmList): 





Parallel Port IOCTL Functions 


The parallel port is generally used to send data to the printer. On AT machines, 
DosWrite and DosWriteAsync can send data to the parallel printer through the 
parallel port. On PS/2 machines, data can also be received from the parallel port 
using DosRead and DosReadAsync. This data can include information on the 
status of the parallel printer, etc. 

However, the ability to simply read and write to a parallel port does not provide 
an application with the functionality it needs to control the printer or to configure 
the parallel port. These functions are provided by category number 5 IOCTL 
functions. Before any category 5 DosDevIOCtl function can be called, the parallel 
port device handle must have been obtained by the application (the device must 
be opened) using DosOpen. However the device IOCTL functions provided by the 
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OS/2 parallel port device driver only supports those printers that accept IBM 
printer control codes. Fortunately, most parallel printers recognize these codes. 

The only configuration parameter for parallel ports that can be controlled is the 
infinite retry parameter. When infinite is set, the parallel port will never time-out. 
It will continuously attempt to send data to the port. Function 44H returns, and 
function 64H changes the infinite retry status. 

Function 42H and 62H respectively change and return the printer configura- 
tion, such as the settings for characters per line and lines per inch. Function 46H 
initializes the parallel printer. Function 66H returns the current printer status 
which allows an application to monitor any events detected by the parallel port 
(1.e., a time-out, I/O error, or out of paper error.) 


Set and Determine Infinite Retry Status: 44H and 64H 


int DosDeviOCtl (PtrRetry, PtrCommand, 0x0044, 0x0005, Device_Handle) 


char far *PtrRetry; 


char far *PtrCommand; 


unsigned Device_Handle; 





Data Block Format (Data): PtrRetry 


Data block in this function is used to specify the infinite retry parameter. 
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Parameter List Format (ParmList): PtrCommand 





int DosDeviOCtl (PtrRetry, PtrCommand, 0x0064, 0x0005, Device_Handle) 


char far *PtrRetry; 
char far *PtrCommand; 


unsigned Device_Handle; 





Data Block Format (Data): PtrRetry 
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Parameter List Format (ParmList): PtrCommand 





Set and Determine Frame Control: 42H and 62H 


int DosDeviOCtl (PtrFrame, PtrCommand, 0x0042, 0x0005, Device_Handle) 


char far *PtrFrame; 
char far *PtrCommand; 


unsigned Device_Handle; 





Data Block Format (Data): PtrFrame 


Data block in this function is used to specify the configuration data. 
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Parameter List Format (ParmList): PtrCommand 





int DosDeviOCtl (PtrFrame, PtrCommand, 0x0062, 0x0005, Device_Handle) 


char far *PtrFrame; 
char far *PtrCommand; 


unsigned Device_Handle; 
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Data Block Format (Data): PtrFrame 





Parameter List Format (ParmList): PtrCommand 





Initalize Printer: 46H 


int DosDeviOCtl (OL, OL, 0x0045, 0x0005, Device_Handle) 
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Data Block Format (Data): NULL 





Parameter List Format (ParmList): NULL 





Get Printer Status: 66H 


int DosDeviOCtl (PtrStatus, OL, OxO0066, 0x0005, Device_Handle) 


char far *PtrStatus; 


unsigned Device_Handle; 





Data Block Format (Data): PtrStatus 
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Each bit of the value specifies a particular condition. If the bit is set, the 
condition has been detected by the device driver. The following is a list of the 
possible bit values and their meanings: 





Parameter List Format (ParmList): NULL 
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Asynchronous Port IOCTL Functions 


Earlier we learned how to open a communications port with DosOpen, and 
send data to it using DosWrite, and read data from such a port using DosRead. 
These functions, however, are not enough for communicating through an asyn- 
chronous port. In order to perform asynchronous communication, a program 
needs to be able to manipulate the baud rate, line characteristics, XON/XOFF 
status, and other modem control signals for an asynchronous port. 

The IOCTL functions used to manipulate the asynchronous port belong to 
category 1. These IOCTL functions are crucial because they perform functions 
that cannot be provided with OS/2 API functions. Before we discuss these 
functions, however, we need to introduce some of the issues involved with 
manipulating an asynchronous port device driver. 

The asynchronous driver is an interrupt-driven driver which makes it possible 
for the system to perform other tasks while data tranmission and reception are 
taking place. The most important features of this driver are the transmit and 
receive queues. These queues are instrumental in preventing data loss during 
communication, because asynchronous adapters only have a l-byte long data 
buffer, which is not enough to handle a transmission rate of even 300 baud on its 
own. The asynchronous device driver must also be configured to handle a variety 
of communications protocols, operate the modem control signals such as XKON/ 
XOFF, data terminal ready (DTR), request to send (RTS), data carrier detect 
(DCD), and ring indicator (DI). 

In this section the primary objective is to provide the syntax and basic use of the 
IOCTL functions for asynchronous communication. We regret that we cannot 
launch a discussion of the various types of communications protocol, and pre- 
ferred communications programming techniques, but any discussion that would 
be adequate to the material would be out of place in this text. A reference 
dedicated specifically to asynchronous communication should be consulted for 
guidance on how to use these features provided by OS/2. 


Line Characteristics 


Manipulating the line characteristics for asynchous communication includes 
changing and determining the status of the serial port and of the modem attached 
to the port. [OCTL functions are provided for setting and determining the baud 
rate, parity, stop bits, and modem control signals. The baud rate can be deter- 
mined and set using function number 61H and 41H, respectively. Parity, stop and 
data bits can be determined and set using functions 62H and 42H. Modem control 
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signals can be changed using function number 46H. The current settings for the 
output and input modem signals can be determined using functions 66H and 67H, 
respectively. 

Modem control signals are DTR (data terminal ready) and RTS (ready to send). 
DTR can be set to have any of the following statuses: enabled, disabled, or input 
handshaking. RTS can have any of the following statuses: enabled, disabled, input 
handshaking, or toggling on transmit. Function 46H can only be used to switch 
between enable and disable. This function should not be used when DTR or RTS 
is in the input handshaking or toggling on transmit state. Input handshaking 
mode allows the device driver to control the staus of the DT’ Rand RTS in response 
to the size of the queue. Toggling on transmit mode allows the device driver to 
control RTS when it wants to transmit data. These signals should only be used if 
the serial port is attached to a DTE device that requires the use of these signals. 


Baud Rate Functions: 41H and 61H 


int DosDeviOCtl (OL, BaudRate, 0x00041, 0x0001, Device_Handle) 


unsigned far *BaudRate; 


unsigned Device_Handle; 





Data Block Format (Data): NULL 


Parameter List Format (ParmList): BaudRate 
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int DosDeviOCtl (BaudRate, OL, 0x00041, 0x0001, Device_Handle) 


unsigned far *BaudRate; 


unsigned Device_Handle; 





Data Block Format (Data): BaudRate 





Parameter List Format (ParmList): NULL 
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Parity, Stop, Data Bits Function: 42H and 62H 


int DosDeviOCtl (OL, LineParm, 0x00042, 0x0001, Device_Handle) 


unsigned far *LineParm; 


unsigned Device_Handle; 





Data Block Format (Data): NULL 


Parameter List Format (ParmList) LineParm 





This call only affects the format of the data that is received after the call is made. 
Data already on the receive queue is not affected. 
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If the data bit is less than 8 bits long, the driver does not truncate any 
tranmission control data sent by the application to the device driver. No error is 
generated if any error control data has high order bits with a non-zero value. If the 
application sets the data bit to 7, and the XOFF character is set to 82H, the driver 
will not be able to receive any XOFF character because any value greater than 80H 
will automatically be truncated by the data bit setting. [fan error control character 
is set to 82H, however, the driver receives this value without truncating it. 


int DosDeviOCtl ( LineParm, OL, Ox00062, 0x0001, Device_Handle) 


unsigned far *LineParm; 


unsigned Device_Handle; 





Data Block Format (Data): 
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Parameter List Format (ParmList): NULL 


Set Modem Control /Signals (DTR & RTS): 46H 


int DosDevi0OCtl (CommError, ModemSignal, 0x00046, 0x0001, Device_Handle) 


unsigned far *CommError; 


struct ModemCntrl far *ModemSignal; 


unsigned Device_Handle; 





Data Block Format (Data): CommError 
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Parameter List Format (ParmList): ModemSignal 





or 


struct ModemCntrl { 
char ModemOn; 
char ModemOff; 
} 


The use of these values is a little bit confusing. Essentially only bits 0 and 1 of 
both masks have any significance. Bit 0 represents the status of the DTR and bit 
1, the RTS status. Enabling one of the mode control signals is done by setting its 
associated bit in the ON mask. Disabling one of the mode control signals involves 
clearing its associated bit in the OFF mask. So, one should understand that all the 
bits in the ON mask are clear, except for those which one wishes to set; and all the 
bits in the OFF mask are set except for those that one wishes to clear. If any other 
bits in the ON mask are set besides 0 and I, and if any other bits in the OFF mask 
are set besides 0 and 1, the function returns an error. For example, if bit 0 in the 
ON mask is set (to 1), then the DIR is enabled. If bit 0 of the OFF mask is cleared 


750 Advanced Programmer's Guide to OS/2 


(off or 0), the DTR is disabled. If the above values are specified during the same 
call, then they would be in conflict with one another (the DTR is requested to be 
both enabled and disabled at the same time). If there is such a contradiction, the 
bit in question is translated as set. 


Bit ON Mask Value OFF MASK Value Meaning 
0 1 DTR set 

0 0 DTR clear 
] 1 RTS set 

] 0 RTS clear 


Table 18.4 Bit values for DIR and RIS. 


The default value is to disable both DI Rand RIS. This function cannot be used 
when the DTR is set to input handshaking, or the RTS is set to input handshaking 
or toggling on transmit. In such a case, an error is returned. 

The hex values in table 18.5 can be used. 


ON MASK OFF MASK Meaning 
01H FFH Set DTR 
OOH FEH Clear DTR 
02H FFH Set RTS 
OOH FDH Clear RTS 
03H FDH Set DTR and RTS 
OOH FCH Clear DTR and RTS 


Table 18.5 Hexadecimal values for DTR and RIS. 


Determine Modem Control Input and Output Signal: 67H and 66H 


Function 67H returns the current status of the modem input signal. For 
example, if the phone is currently ringing, then the RI bit is ON. Function 66H 
returns the current status of the modem output signal (the DTR and RTS). To 





Device |/O Control Functions 751 


immediately detect any status changes, an asynchronous thread would have to be 
set up to continously call these functions. Device drivers do not have event noti- 
fication capabilities. 


int DosDeviOCtl (PtrModemOutput, OL, Ox00066, 0x0001, Device_Handle) 


char far *PtrModemOutput; 


unsigned Device_Handle; 





Data Block Format (Data): PtrModemOutput 
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Parameter List Format (ParmList): NULL 


int DosDeviOCtl (PtrModeminput, OL, Ox00067, 0x0001, Device_Handle) 


char far *PtrModemInput; 


unsigned Device_Handle; 





Data Block Format (Data): PtrModemInput 
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Parameter List Format (ParmList): NULL 


Transmit and Receive Queues 


Whenever a character is received by the asynchronous port it generates an 
interrupt. This allows the serial port device driver to take the character from the 
adapter and put in its receive queue. When data is sent by the application, it is 
placed on the transmit queue and the device driver sends it to the serial port. 

The maximum size of the transmit and receive queues are currently 128 bytes 
and 1K respectively. The maximum size of these queues may be changed in later 
releases of OS/2. 

Function 69H returns the maximum size of the transmit queue and the number 
of bytes currently on the queue. This function can be used by applications to 
determine the maximum number of bytes that can be sent with DosWrite and 
DosWriteAsync, which will immediately be placed on the transmit queue. When 
using DosWrite and DosWriteAsync to write to an asynchronous port, the device 
subsystem accepts data from the write call and passes it on to the device driver in 
increments that fit on the transmit queue. When these bytes have been sent by the 
port, it then gets more characters from the write calls. This process continues until 
all the data to be written with DosWrite or DosWriteAsync is sent to the transmit 
queue. Ifan application sends only as much data to the asynch portas will currently 
fit on the transmit queue, then it can be assured that its write calls will be serviced 
immediately. 

The number of bytes on the transmit queue returned by function 69H may not 
actually reflect the number of bytes which the application can immediately send 
to the device driver. This would be the case if there were anumber of write requests 
still waiting to be filled. ‘To prevent this from happening, a process should dedicate 
a single thread for writing to the asynchronous port. 
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Function 68H returns both the maximum size and the current size of the receive 
queue in number of bytes. This function determines the number of bytes which 
can immediately be read from the asynch port with DosRead or DosReadAsync. If 
a program requests more data than is currently on the queue it must wait for the 
receive queue to fill up to the requested value before the read call returns. 

The number of bytes on the receive queue returned by function 69H may not 
actually reflect the number of bytes which the application can immediately read 
from the asynch port. This would be the case if a number of read requests were 
waiting to be filled. To prevent this from happening, a process should dedicate a 
single thread for reading from the asynch port. 


Current size of receive queue: 68H 


int DosDeviOCtl (PtrRecvQueue, OL, 0x00068, 0x0001, Device_Handle) 


struct QueueStatus far *PtrRecvQueue; 


unsigned Device_Handle; 





Data Block Format (Data): PtrRecvQueue 
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Or 


struct QueueStatus { 
unsigned Characters; 
unsigned MaxChar_inQueue; 


Parameter List Format (ParmList): NULL 


Current size of transmit queue: 69H 


int DosDeviOCti (PtrTransQueue, OL, OxO00069, 0x0001, Device_Handle) 


struct QueueStatus far *PtrTransQueue; 


unsigned Device_Handle; 





Data Block Format (Data): 
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or 
struct QueueStatus [{ 
unsigned Characters; 
unsigned MaxChar_inQueue; 
| 
Parameter List Format (ParmList): NULL 


Logical Flow Control 


These functions do not determine whether the device driver will use XON/ 
XOFF for data transmission and reception. They do, however, allow a program to 
temporarily change the logical flow of the data. The program can use function 
47H to stop data transmission and 48H to restart it, as ifan XOFF and XON have 
been received, respectively. Function 44H transmits a character immediately. The 
character will be put in front of other characters in the transmit queue. This 
function is often used by an application to send an XON or XOFF character 
manually. 
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Stop Transmit (XOFF): 47H 


int DosDeviOCtl( OL, OL, Ox0047, 0x0001, DeviceHandle) 


unsigned DeviceHandle; 





Data Block Format (Data): NULL 


Parameter List Format (ParmList): NULL 


Transmission can be resumed by one of the following events: an XON is 
received, function 48H is issued, or the automatic transmit flow control is switched 
from enable to disable. If automatic flow control is off, no XON can be received. 
Function 48H must be issued in order for data transmission to be resumed. 


Start Transmit (XON): 48H 


int DosDeviOCtl( OL, OL, Ox0048, 0x0001, DeviceHandle) 


unsigned DeviceHandle; 





Data Block Format (Data): NULL 


Parameter List Format (ParmList): NULL 
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Transmit Immediate: 44H 


int DosDeviOCtl(OL, TransChar, 0x0044, 0x0001, DeviceHandle) 


char far *TransChar; 


unsigned DeviceHandle; 





Data Block Format (Data): NULL 


Parameter List Format (ParmList): TransChar 





The character is put in front of the transmit queue. The XON/XOFF character 
might be in front of this character if automatic flow control is enabled. 

The device driver might not be able to transmit this character immediately if 
output handshaking is enabled or if a break is currently being transmitted. A 
general failure error will be returned if there is an immediate transmit character 
left over from a previous request still in the transmit queue. 

This function can be used to transmit an XON/XOFF character manually by an 
application. It should not, however, be used when XON/XOFF protocol is 
enabled and the automatic data flow is currently in the disabled state. Doing this 
might cause an unexpected error because the receiving side does not expect a 
character. Also the immediate transmit character is not considered to be part of 
the transmit queue, and is not cleared from the queue by a flush request. 
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Break Processing 


Break processing is the capability to send a break signal to the communication 
port. Function 4BH is used to send a break signal immediately and continue 
sending until function 45H is issued. During the transmission of a break signal, no 
other data on the tramsit queue is sent. 


Break On: 4BH 


int DosDeviOCtl (CommeError, OL, OxO004B, 0x0001, DeviceHandle) 


unsigned far *CommEtrror; 


unsigned DeviceHandle; 





Data Block Format (Data): CommError 





Parameter List Format (ParmList): NULL 
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Break Off: 45H 


int DosDeviOCtl (CommError, OL, Ox0045, 0x0001, DeviceHandle) 


unsigned far *CommError; 


unsigned DeviceHandle; 





Data Block Format (Data): CommError 





Parameter List Format (ParmList): NULL 


Serial Port Status 


The complete status of the serial port is contained in the following three 
structures: the communication event word, communication status word, and the 
transmission status word. Communication errors are also part of the serial port 
status. 

The communication event status word contains values associated with the 
signals generated by the RS-232 device or with values associated with the pins on 
the adapter itself. These values consist of the status of transmit/receive, CTS, DSR, 
DCD, break, and RI signals, and any communication errors. Function 72H returns 
the communication event status word. 
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The communication error status word contains values generated by the device 
driver to inform the application of problems occurring during the communica- 
tion. Function 6DH returns the communication error status word. This structure 
is usually referred to as COMERR. 

Function 64H returns the current communication status word which represents 
the information that effects the logical flow of the communication. The status 
includes information on whether a transmission is waiting for XON/XOFF, CTS, 
DSR, DCD or, break. 

Function 65H returns the transmission status word which includes information 
describing the current stage of the transmission process such as whether data is 
being sent by the application, data is in the transmit queue, or the adapter is 
currently transmitting data, etc. 


Communication Event Information: 72H 


int DosDeviOCtl (CommEvent, OL, 0x0072, 0x0001, DeviceHandle) 


unsigned far *CommEvent; 


unsigned DeviceHandle; 





Data Block Format (Data): CommEvent 
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The communication event status word reflects the values of the pin signals on 
the RS-232 device. The status is a bit-mask value. Each bit, when set, indicates that 
the particular event has occurred. The possible bit values are as follows: 





Parameter List Format (ParmList): NULL 


Communication Error: 6DH 


int DosDeviOCtl (CommError, OL, OxOO6D, 0x0001, DeviceHandle) 


unsigned far *CommError; 


unsigned DeviceHandle; 
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Data Block Format (Data): CommError 





The communcation error status word represents the errors detected by the 
device driver during communication. The application should use this function in 
order to perform error recovery. Each bit of the COMERR represents a specific 
error. If the bit is set, the error it represents was detected by the driver. 
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Parameter List Format (ParmList): NULL 


Communication Status: 64H 


int DosDeviOCti (CommStat, OL, Ox0064, 0x0001, DeviceHandle) 


unsigned far *CommsStat; 


unsigned DeviceHandle; 





Data Block Format (Data): ComStat 





The communication status word represents the current status of the logical flow 
of the communication process (i.e., whether if the driver is waiting because of 
XON/XOFF or other flow control signals). The communication status is a bit- 
masked value with each bit representing a particular event. If the bit is set, the 

event it represents was detected by the device driver. 
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Parameter List Format (ParmList): NULL 


Transmission Status: 65H 


int DosDeviOCti (TransStat, OL, Ox0065, 0x0001, DeviceHandle) 


char far *TransStat; 


unsigned DeviceHandle; 





Data Block Format (Data): 
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The transmission status word is a bit-masked value with each bit representing a 
particular event. If the bit is set, the event it represents was detected by the device 
driver. 





Parameter List Format (ParmList): NULL 


Device Control Block Parameters 


The device control block parameters contain all the parameters that the device 
driver will use for the tranmission and reception of data. These include setting 
values for the following parameters: read/write time out; modem control signals: 
DTR, CTS, DSR and DCR; XON/XOFF control; the error replacement character; 
null stripping; the break replacement character; and the RTS control signal. The 
values of these combined parameters provide a very complex protocol which the 
device driver uses to send and receive data. If an application only needs to send 
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data ata certain baud rate, parity, data bit, and stop bit, it does not have to deal with 
such complex issues as setting values for XON/XOFF or DTR and RIS. 

Function 53H sets the DCB parameters and function 73H returns the current 
DCB parameters. Unfortunately function 53H wipes out the preceding values for 
the DCB, so all the values for the DCB have to be provided when using it. To 
selectively modify the DCB use function 73H to obtain a copy of the current DCB, 
make changes to the desired fields of the returned data structure, then write the 
DCB back to the system using function 53H. 


Set Device Control Block Function: 53H 


int DosDeviOCti (OL, PtrDCBblock, 0x0053, 0x0001, DeviceHandle) 


struct BPB far *PtrBPB; 


unsigned far *DeviceHandle; 





Data Block Format (Data) NULL 


Parameter List Format (ParmList): PtrDCBBlock 
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This structure can be described in C as follows: 


struct DCE { 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 


} 


short Write..Jime Out: 
short Read_Time_Out; 
DCB_Flags1; 
DCB_Flags2; 

DCE Flages : 
Err_Replace_Char; 
Break_Replace_Char; 
XON Char: 

XOFE Char: 


The DCB parameters are controlled by the parameters DCBFlags1, DCBFlags2, 
and DCBFlags3. These are byte-long bit-masked values. Ifa specified bit is turned 
on then the associated feature is enabled. Any attempt to specify a value for a 
reserved field within a parameter will meet with a “General Failure” error. 

DBBFlags1 governs the control and handshaking modes for a device: 
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DCBFlags2 governs the flow control and replacement character modes for the 
device: 





DCBFlags3 governs the time-out processing for the device. When using function 
53H only one value can be specified for this parameter. 
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Determine Device Control Block Function: 73H 


int DosDeviOCtl (PtrDCBBlock, OL, 0x0073, 0x0001, DeviceHandle) 


struct BPB far *PtrDCBBlock; 


unsigned far *DeviceHandle; 





Data Block Format (Data) PtrDCBBlock 


Parameter List Format (ParmList): NULL 


This function returns a data structure identical to the one returned by 53H. 
Please refer to the preceding discussion for its structure. 


Chapter 19 


Input/Ouput Privilege Level 
Segment 





Level (IOPL). Any segment in a program running at this level is, therefore, 

called an IOPLsegment. OS/2 provides the ability to define I[OPL segments 
to allow those programs whose I/O needs are not met by the standard or extended 
(programmer-replaced) device subsystem, or by the IOCTL functions provided by 
each device driver, to achieve the I/O services they need. Running at IOPL gives 
a program the ability to directly send and receive data from the hardware I/O ports 
using the 80286 instructions IN and OUT. For those of you unfamiliar with the 
hardware I/O ports, you should know that each hardware device attached to the 
80286 CPU is assigned a hardware port I/O number. The IN instruction allows a 
calling program, to receive data sent from a device to the hardware I/O port, and 
the OUT instructon allows a program to send data to the hardware I/O port. 
Under DOS, applications would often use the IN and OUT instructions to achieve 
I/O rates that are faster than those provided by the BIOS services. However, under 
OS/2 the use of these instructions is limited to those code segments which are 
explicitly declared as IOPL segments. 

IOPL segments are used to give programs greater I/O capabilities than those 
provided by any of the standard I/O interfaces without having to go to the extreme 
of providing its own device driver. IOPL segments, however, can only be used for 
non-interruptible devices. Devices such as the asynchronous port or the keyboard 
are interruptible devices and cannot be accessed by an IOPL segment. This 
limitation makes IOPL segments, for the most part, useful for applications which 
need to directly manipulate video adapters and the speaker (which are non- 
interrupt driven devices). In fact, in order for a graphics application to be able to 
directly manipulate the registers of the EGA or the VGA, it must establish an IOPL 
segment. 


S ome program segments execute at privilege level 2: the Input Output Privilege 
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Privilege Level 0 


OS/2 subsystems 


and device drivers 


Figure 19.1 Relationship between IOPL segment, applications and operating 
system 





In this chapter, we will explain how to define and create an IOPL segment, 
describe the syntax of useful IOPL API functions, and provide guidelines for the 
use of IOPL segments. Remember that IOPL is only applicable for non-interrupt 
driven devices and should be used only when the standard device subsystems will 
not provide the same services. 


Features of IOPL Segment 


A program might be divided into many segments of code. By using the program 
module definition file (.DEF) during link time, certain segment(s) of the program 
can be defined as IOPL segments. Because an IOPL segment executes at privilege 
level 2, it cannot access system services via the API provided by OS/2 for privilege 
level 3. Nor will it have access to IOCTL functions provided by the device drivers. 
An IOPL segment only has access to its own data segment and the data segments 
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IOPL Segment 


Cannot register, 
receive or process 
interrupts 


No access to OS/2 
API services or 
IOCTL functions 


Can be called from a 
dynalink routine. 


Used for non-inter- 
rupt driven device, 
polling device or 
output devices such 
as video adapter. 


Segment is loaded 
into memory when 
the segment is called, 
and unloaded when 
the segment finishes 
executing. 


2 


Can issue CLI/STI 
instruction to clear/ 
restore interrupts. 


Device Driver 


Complete interrupt 
SEIVICes 


Most of these services 
are available via 
DevHlp function. 


Cannot be called from 
a dynalink routine. 


Used for any type of 
device. 


The device driver code 
and data segments 
must always be resi- 
dent in memory. 


Can issue CLI/STI 
instruction to clear/ 
restore interrupts. 


Table 19.1 Differences between device drivers and IOPL segments. 


belonging to the process to which it belongs. Because of these heavy restrictions 
on its operation, an IOPL segment should (and can) only be used to perform I/ 
O to a specific device as a proxy for other modules in the program to which it 


belongs. 


An IOPL segment is similiar to a device driver in that both can issue the 80286 
An IOPL segment, however, cannot service the 
interrupts generated by certain hardware devices. For I/O operations that require 
interrupt handling a device driver must be written instead. 

Table 19.1 summarizes the differences between device drivers and IOPL 


IN and OUT instructions. 


segments. 
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Setting Up an IOPL Segment 


An IOPL segment can only be instituted if the system is configured to allow for 
it. The IOPL configuration is determined by a parameter in the Config.sys file. 
Including the following statment in the Config.sys file allows for the execution of 
IOPL segments (the default is no IOPL): 


IOPL = YES 


Once the system is configured, the programmer must explicitly define /identify 
the IOPL segment through a statement in the module definition file for the 
application when it is being linked. For most applications a module definition file 
is optional, but for applications that include IOPL segments they are required. 
IOPL segments should be created in separate source files, and compiled separately 
to make sure that they reside on their own segments after linking (each object 
module will generally be linked as a separate code segment). 

Once the system is configured, the programmer must specify in the module 
definition file which segment of the code is the IOPL segment. A program is 
usually composed of several object modules. Each object modules is compiled 
separately by the compiler. The linker then links all the object modules into one 
program. Each object module is treated as a separate code segment. Because an 
IOPL segment cannot call any API function, the programmer should make sure 
that the IOPL source modules are to be compiled separately from other modules. 

If the IOPL segment is to be implemented as one of the segments in the 
execution module, then a SEGMENTS statement identifying that segment by 
name must appear in the module definition file for that application. This 
statement will contain at least the following information 


SEGMENTS 
TOPLSegName IOPL 


where JOPLSegNameis the name of the IOPLsegment. ThisSEGMENTS definition 
can also include information about whether it is to be pre-loaded or loaded-on-call, 
execute only, or both execute and read (please see Chapter 9 for further 
information). 

If the IOPL segment is to be implemented as part of a dynamic link library then 
it will also have to be mentioned in the EXPORTS statement of the module 
definition file. The form of the EXPORTS declaration for an IOPL routine in a 
dynamic link library differs from that of a regular export routine in that only two 
arguments can appear in the EXPORT statement for it 
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EXPORTS 
ITOPLRoutNmame IOPL-Parm# 


where JOPLRoutNmame is simply the name that will identify the IOPL segment for 
export purposes, and /OPL-Parm# is an integer number representing the number 
of words to be copied from the callers stack to the IOPL routine. 


Guidelines for Developing IOPL Segments 


There are two issues that must be dealt with when writing IOPL segments. One 
is protecting a device that is an SRR, and the other is the way in which an IOPL 
routine protects itself from being interrupted during its access of the I/O port by 
another unrelated IOPL segment (the SRR problem again), or even by the 
operating system. This latter point is particularly important since the operating 
system does not provide serialization for IOPL segments. 

In order to protect a device that is also an SRR, the IOPL segment will have to 
prevent itself from making multiple simultaneous calls to the device. This is 
especially important for IOPL routines implemented from a dynamic link library. 
For an IOPL segment implemented within a process, the IOPL segment should 
simply set up a private semaphore using a global variable. When the first IOPL 
thread is launched it should set this variable to some pre-established value (say 1), 
once it finishes it should reset the value (to, say, 0). Whenever another IOPL 
thread is launched it should first check the status of this semaphore to see whether 
the device is already in use. If the device is free the IOPL thread can execute, if not, 
the call will have to fail or wait. Alternately more complicated serialization shemes 
can be developed, though not within the API segment itself (since API calls are not 
valid within IOPL segments). However, such serialization can be accomplished by 
an intermediary routine outside the [OPL segment which is called, and then in 
turn calls the IOPL segment (in the manner of the OS/2 router mechanism used 
by device subsystems). Providing synchronization for an IOPL segment imple- 
mented as a dynamic link library routine is a similar matter. 

When an IOPL segment accesses an SRR device there is the always the chance 
that another unrelated IOPL segment active within the system might interrupt the 
I/O operations carried out by the first. This might lead to the corruption of data 
or even to damage of the device. In some situations it may be desirable to keep an 
IOPL routine from being interrupted at all. In order to guard against being 
interrupted while executing its “critical section” an [OPL routine can temporarilly 
disable all system hardware interrupts. This is done by issuing the CLI instruction 
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upon entering the critical section and STI when leaving it. This, however, is a 
radical maneuver, because the system cannot service any type of interrupt when a 
CLI instruction is in effect. All operating system functions including task switching 
and segment swapping are disabled at this time. Ifan I/O request takes along time, 
the entire system does nothing during the waiting period. In addition, any 
interrupts generated during this time are lost, which can easily result in a loss of 
data or other inconsistencies. 

If an IOPL routine needs to disable hardware interrupts, the routine must 
conform to the following guidelines in order to insure the integrity of the system: 


= DosCLIAccess must be called by the IOPL segment to obtain approval from 


the operating system before hardware interrupts are disabled. 


= The critical section must be as quick as possible. ‘The IOPL segment should 


simply issue an IN or OUT instruction during the critical section that 
requires the disabling of hardware interrupts. 


" While the interrupts are disabled, the ILOPL segment should not change any 


segment registers. This includes making a FAR call to another segment. 
Changing the segment register might cause the 80286 to generate a 
segment-not-present exception, which only can be handled by OS/2. 
OS/2, however, cannot handle this exception because the interrupts are 
disabled. ‘The system will hang in this situation. 


The IOPL segment can change the segment register in two cases: (1) if the 
new content of the segment registers is a selector of asegment that has been 
locked in physical memory by a device driver (the only way a program can 
know about the segment register of another device driver is if that program 
was designed to work in conjunction with the driver); (2) if changing the 
contents of the segment register involves loading the content of a selector 
of the global or local information segments which are always memory 
resident. 


The IOPL segment should not attempt any instruction which might 
generate any type of 80286 exceptions. 


IOPL Segment and the 80386 


The 80386 was designed to restrict access to hardware I/O ports. In order to 
issue the IN or OUT instructions in an 80386 running OS/2, the application first 
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must obtain permission from the CPU using the function DosPortAccess. DosPort- 
Access automatically grants the program access to a particular I/O port and 
permission to issue the CLI/STI instruction without issuing DosCLIAccess. 

DosPortAccess can also be issued by an application running in the 80286 CPU. 
This function simply serves as an equivalent to function DosCLIAccess, because the 
80286 automatically grants access to all hardware I/O ports when a program is 
running under privilege level 2. 


IOPL Functions 


There are two IOPL related API functions: DosPortAccess and DosCLIAccess. 
DosPortAccess obtains permission from OS/2 for the IOPL segment to access a 
hardware I/O port. DosPortAccess also obtains approval to disable/enable 
hardware interrupts just as function DosCLIAccess. Therefore, whenever the 
program issues DosPortAccess, it does not have to call DosCLIAccess. It is 
recommended that function DosPortAccess should be used so that the IOPL 
segment can be executed in a 80386-based system. 


DosPortAccess 


DosPortAccess serves two purposes: to request access to hardware I/O ports 
and later to release access. ‘The type of access is defined by parameter TypeOfAccess 
and the port number range is defined with the starting port number, FirstPort, and 
the last port number, LastPort. If the program only needs access to one port, the 
first port number and the last port number should be the same. 


DosPortAccess (Reserved, TypeOfAccess, FirstPort, LastPort) 


unsigned Reserved; /* must be zero */ 
unsigned TypeOfAccess; /* access request or release */ 
unsigned FirstPort; /* first port number */ 


unsigned LastPort; /* last port number */ 
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DosCLlAccess 


Function DosCLIAccess grants the calling IOPL thread permission to issue the 
assembly instructions CLI or STI to disable or restore hardware interrupts gener- 
ated by the system hardware devices. This functions expects no parameters. 

A succesful return of 0 indicates that the CLI/STI request has been approved. 
A non-zero value indicates an unsuccessful call. 


IOPL Example Program 


The sample IOPL program included here duplicates the functionality of the 
OS/2 function DosBeep. DosBeep takes two arguments: frequency (in hertz) and 
duration (in milli-seconds). Since it does not fall under any of our other categories 
we demonstrate its use here as well. The first example uses the DosBeep function 
to generate a tone with the speaker. The second example uses an IOPL segment 
to do the same thing by directly manipulating the speaker port and the program- 
able timer. In the IJOPL example, Beep.asm, a time delay is specified after calling 
the OUT function. Specifying a time delay ensures that the hardware has the 
opportunity to satisfy an output request. 
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/* DOSBEEP.C 


This program demonstrates how to use DosBeep to generate sound from 


the speaker. DosBeep requires two parameters: frequency and 
duration. The frequency ranges from 37 to 32767 Hertz (cycles per 
second). The duration is measured in terms of milliseconds. 


Both frequency and duration parameters are unsigned or WORD 
variables. 


+f 
fFinclude <doscalls.h> 
main() 
{ 

unsigned frequency, duration; 

duration = 80; /* 80 milliseconds */ 

for (frequency=37; frequency < 32767; frequencytt) { 

DOSBEEP(frequency,duration) ; 
DOSSLEEP(100L): /* pause for 1/10 of a second */ 

} 
Beep. DEF 
NAME BEEP 
PROTMODE 
SEGMENTS IOPLCODE CLASS ‘IOPLCODE’ IOPL ;Defines segment attributes 
/* SPEAKER.C 
This program will call IOPL segment routines beep_on() and beep_off() 
This program will mimic the DOSBEEP.C which will generate sounds from 
the speaker, but will use an IOPL segment instead of the DOSBEEP API 
call. 
ae i 
fHinclude “doscalls.h” 


ttdefine SPEAKER 0x61 
ttdefine TIMEROx40 


extern unsigned frequency; 
extern far beep_on(); 
extern far beep_off(); 
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void beep(freq,duration) 
unsigned freq; 
unsigned duration; 


{ 


frequency = freq; 
beep_on(); 
DOSSLEEP((long)duration) ; 
beep_off(); 

} 

main () 


{ 
unsigned freq, duration; 
unsigned ret; 


duration = 80; /* 80 milliseconds */ 

ret = DOSPORTACCESS (0, /* request access to speaker port */ 
Oo: /* rvaquest daceess */ 
SPEAKER, 
SPEAKER) ; 

if (ret) { 


printf£(“\nDosPortAcces failed (speaker): %d”,ret):; 
DOSERIT (1,0): 
} 


ret = DOSPORTACCESS (0, /* request access to all timer ports. */ 
QO, 
TIMER, 
TIMERTS } : 

if Leet) 4 


printf(“\nDosPortAcces failed (timer): %d”,ret); 
DOSEXIT(1,0); 
} 


for (freq=37; freq < 32767; freqtt) { 
beep(freq,duration) ; 


DOSSLEEP(100L) ; /* pause for 1/10 of a second */ 

} 

DOSPORTACCESS (0, /* release access to speaker port */ 
1, /* release access */ 
SPEAKER, 


SPEAKER) ; 








Input/Output Privilege Level Segment 783 


DOSPORTACCESS(0, /* release access to all timer ports */ 
| ’ 
TIMER, 
TIMERTS ) : 


DOSEXIT(1 0): 


; BEEP.ASM 
;This program demonstrates how to program an IOPL segment. 


;The IOPLCODE segment must be defined as an IOPL segment in the .DEF 
file 

;We will use the AT programmable timer to generate the frequency 
;For more info, consult the Technical Reference. 

;Remember, in the config.sys file, you must have 

: LOPL=YES 

sin order to allow program access to the IOPL 


.286p 


_DATA SEGMENT WORD PUBLIC ‘DATA’ 


timer equ 40h - $254 timer/counter port first address 
speaker equ 61h ; 8042 Speaker Device port number 
port_setting db 0 ; area to save speaker port orig. setting 
_frequency dw 0 ; frequency in hertz 

oscillator dd 1193167 ; frequency oscillator 


_DATA ENDS 

CONST SEGMENT WORD PUBLIC ‘CONST’ 

CONST _ ENDS 

_BSS SEGMENT WORD PUBLIC ‘BSS’ 

_BSS ENDS 

DGROUP GROUP CONST, _BSS, _DATA 

: EXTRN DOSPORTACCESS: FAR 

IOPLCODE segment word public ‘ITOPLCODE’ 
assume es: ITOPLCODE, ds:dgrotp 


; these variables will be accessed by the C program. 
public _beep_on, _beep_off, _frequency 


784 


_BEEP_ON PROCfar 


’ 


’ 
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setup the timer to receive the divisor 


mov bx, frequency; 
mov al,OB6h 
out timert3,al 


calculate the divisor 


frequency in hertz 
timer-mode register signal 


mov dx,word ptr oscillatort2 
mov ax,word ptr oscillator 


div bx 


output the divisor to the 
out timert2,al 
jmp short $+2 
mov al,ah : 
out timert2,al : 
jmp short St2 


turn on the speaker 


in al,speaker : 


timer 
ouput LSB of the divisor to the timer 
time delay - necessary for the hardware 


move MSB to the register 
output MSB of the divisor to the timer 
time delay | 


read the bit-setting of speaker port 


mov port_setting,al.; save the port-setting 


jmp short $+2 
ox al,03 : 


out speaker,al 


ret 


_BEEP_ON END? 


time delay 
turn on the last bits 


write the new value to the speaker 
speaker is now on 


Routine to turn the speaker off 


_BBEPOFEF PROG far 


mov al,port_setting 


or al, Q1 
out speaker,al 


ret 


_BEEP_OFF ENDP 


IOPLCODE ENDS 


END 


; restore original port-setting 


output value to speaker 
speaker is now off 





Chapter 20 


Character Device Monitors 


haracter device monitors are one of the advanced methods OS/2 provides 

for receiving data from a device. A character device monitor is a process 

which can monitor as well as modify the data stream a character device driver 
sends to its device subsystem. A keyboard monitor can monitor and change the 
keystroke information sent from the keyboard device driver to the keyboard 
subsystem. Similarly, a mouse monitor has the ability to monitor and modify the 
events sent from the mouse device driver to the mouse subsystem. 

Because a device monitor can modify the data stream sent from a device driver 
to its subsystem, it can be used to modify the data received by another application. 
For example, a keyboard monitor can be written that changes all uppercase 
characters on the data stream to lowercase. Once the monitor has been installed, 
an application that subsequently uses KBDxxx API functions to read data from the 
keyboard will only receive lowercase characters, even if the user enters upper case 
characters. A device monitor is a powerful tool and must be used after careful 
consideration of its impact on other applications. 

Device monitors, however, have limited capabilities. Monitors written for the 
mouse and keyboard drivers can only monitor data sent between the device driver 
and their respective device subsystems, and not data sent from the device subsys- 
tem to the driver. Mouse and keyboard monitors are an efficient way to modify data 
that is sent to an application. Because device monitors have access to the data 
stream prior to the device subsystem, they can be used to allow processes running 
in the background to receive user input, such as providing a background process 
with pop-up capability. Device monitors written for the parallel printer port can 
modify the data stream sent by the printer to the application (printer status, error 
codes, etc.) as well as modifying the data stream that is sent by the printer device 
driver to the parallel port. This latter capability is a powerful one, and allows device 
monitors to be used for the implementation of print spoolers. 
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Device monitors can only be implemented for character device monitors which 
can support the OS/2 device monitor facilities. They cannot be installed for block 
device drivers such as the disk drive device drivers, because block devices do not 
use an asynchronous data stream for information passing. The device driver for 
the serial port is a character driver but does not support device monitors, either. 
The only OS/2 device drivers for which device monitors can be implemented are 
those for the keyboard, mouse, and parallel printer. 

This chapter explains how to write a character device monitor, covers the syntax 
of API functions used to develop the application, and discusses the issues involved 
in writing a device monitor application. The issues we discuss are: the purpose of 
device monitors, the differences between a device monitor and a TSR program, 
performance considerations for writing a device monitor, and guidelines for 
developing device monitors for all character device drivers. 


Device Monitor Architecture 


A device monitor can only monitor one data stream ata time. A character device 
driver, however, can establish more than one data stream. For example, the 
keyboard and mouse drivers define separate data streams for both the logical 
keyboard and mouse handles established for each screen group by the Session 
Manager. This means that in general, a device monitor is specific to a session, 
though it can be installed for any number of sessions. 

Data sent from a device is always received by the device driver. The device driver 
either keeps the data for itself or sends it on to the appropriate data stream 
(because there is a separate data stream for each session). Eventually the 
information in this data stream is placed in a screen group-specific API buffer, 
where it may be read by any thread in that screen group using one of the request 
API functions. When a device driver is installed, it is placed on the data stream 
between the device driver and the API buffer. If several device monitors are 
installed, the data is passed from monitor to monitor. The set of device monitors 
installed for a data stream is called the monitor chain. A monitor, or the set of 
monitors on a data stream together act as a sort of filter which tranforms the nature 
of the information to be placed in the session-specific API buffer. 

A device monitor written for the parallel printer driver can also monitor data 
sent from the printer device driver to the printer. In this case, the device monitor 
occupies a position in the data stream between the printer driver and the paralell 
port connected to the printer. 
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Figure 20.1 Position of device monitor in data stream. 
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To declare itself a device monitor, a process must take the following steps: 


= It must issue the function DosMonOpen to obtain a device handle that will 
allow it to gain access to a device driver data stream. 


= Next it must issue DosMonkReg to register itself as a device driver. 


Once this is done the device driver establishes a monitor dispatcher. The monitor 
dipatcher handles the transfer of data from itself to a device monitor and from a 
device monitor to the next monitor in the series, or to the data stream’s API buffer. 
Each device monitor must also provide input and output buffers to allow it to 
communicate with the monitor dispatcher. 

Once a device monitor is registered, the monitor dispatcher automatically 
places any data records appearing in the data stream in the input buffer of that 
device monitor. The monitor must then issue DosMonRead to transfer this data 
record into a private data buffer which the monitor must also create. After placing 
a record in its private buffer a monitor can either modify this data record, or leave 
it intact. It then writes the record to the output buffer using the function 
DosMonWrite. The monitor dispatcher will remove this record and pass it to the 
input buffer of the next device monitor (where the same process takes place), or 
to the API buffer if no more device monitors are registered for the data stream. A 
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Buffer Buffer Buffer 
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Call DosMonWrite 
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a Device Monitor Dispatcher ia 
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Figure 20.2 Movement of data through monitor chain. 
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device monitor can also choose to “swallow” a data record by not writing it to its 
output buffer. Such a data record is lost, and is not passed to any other device 
monitors or the API buffer. 

It should be clear from the previous discussion that the monitor dispatcher 
passes the datarecords making up a data stream for a device driver from one device 
monitor to the next (each device monitor has the opportunity to modify or swallow 
a data record) until the data record has been passed to every registered device 
monitor in the chain, and finally to the API buffer. The function DosMonClose is 
used to de-register all the device monitors that have been registered for a data 
stream. 

The architecture of the device monitor (chain) forces two issues when it comes 
to the design and implementation of device monitors. Because data records are 
passed from monitor to monitor, the position of a monitor within the chain has an 
effect on what sort of information it will receive. Secondly, because device 
monitors receive data (and can transform this data) before applications, care must 
be taken to insure that applications receive the proper data. These issues are 
discussed in the following two sections. 


Developing Device Monitors 


Because a device monitor (chain) receives all data records on the data stream 
defined by the device driver before any application, the device monitor (chain) 
must be careful not to disrupt the data stream. Data placed in each device 
monitor’s input buffer must be read, processed (modified or left alone) and 
placed or not placed (swallowed) in the output buffer as soon as possible. The 
monitor, therefore, must be fast. It should perform the above operations 
immediately. Any complex operation or calculation requiring an extensive 
amount of time should not be done by the same thread that is responsible for 
requesting data or sending data back to the data stream. The thread that issues 
DosMonRead and DosMonWrite should not wait on any semaphore requesting 
I/O services or any operations which might block the execution of the thread. 

These restrictions on device monitors are necassary in order to insure the 
integrity of the data stream. For example, if the device monitor is for some reason 
blocked by a semaphore waiting function, no data records placed in its input buffer 
can be processed. This blocks the entire data stream, and no data records can be 
received by the other monitors, or by an application waiting to read the API buffer. 
If a device monitor hangs, so does the entire system. 

In almost all circumstances the thread that registers the device monitor using 
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DosMonkeg, should be the same thread that performs the monitor I/O functions 
DosMonWrite and DosMonRead. This thread should have the highest priority of 
all threads within the session accessing that device (stream). This allows the device 
monitor thread to be dispatched before any of the threads which access the API 
buffer. The architecture of the device monitor insures that the data stream 
logically passes through the device monitor before it reaches the API buffer. 
However, if the monitor thread is given a low priority, then threads that issue API 
functions which read the API buffer may be dispatched before the device monitor 
thread has had a chance to process the data. The execution of threads which try 
to read the API buffer before the data stream has been filtered through the device 
monitor (chain) will be temporarilly blocked. This process wastes CPU cycles, 
adversely affecting the performance of an application implementing a device 
monitor. 

It is generally recommended that device monitor threads run at a medium or 
low level time-critical priority. 

Having many monitors on one data stream diminishes the performance of that 
device. Because each monitor must explicitly read a data packet, then return it to 
the data stream, multiple monitors on a data stream eat up CPU cycles. This can 
cause a long delay between the time when a data packet is sent by the device, and 
the time when it is in an API buffer available for use by an application. Keyboard 
monitors are especially vulnerable. When many keyboard monitors are installed, 
keyboard response becomes sluggish. 

Device monitor threads should notrun at the highest level time-critical priority, 
priority 0. This priority level should be reserved for hardware device drivers that 
need to service the interrupts generated by devices such as asynchronous ports, 
network adapters, etc. A network card device driver should have a higher priority 
than a monitor that intercepts the data stream generated by the network driver (in 
the same way as the monitor should have a higher priority than an application 
thread which issues an API function to read the API buffer). A CPU cycle will be 
wasted if the monitor has a higher priority than the device driver, because the 
monitor will simply have to wait until the data is sent to it by the device. Ifthe time- 
critical priority is overloaded with monitors then device drivers will not be able to 
meet the demands of devices. 

Only the monitor thread should have time-critical priority. Any other threads 
within the monitor process should run at the same priority as other OS/2 
applications. 

A general rule that should be kept in mind when writing device monitor 
applications is that a well-intentioned device monitor should be self-contained and 
should not be dependent on or have any effect on the execution of other monitors 








Character Device Monitors 79] 


or other applications. In other words, a device monitor should not swallow or 
otherwise destructively alter data required by other device moniters or applica- 
tions. Keeping this in mind, there are a few other issues which the programmer 
must understand. These include: the significance of the position of a device 
monitor within the monitor chain, the structure of the monitor input and output 
buffers, the structures of the data records passed by the different types of device 
drivers to which monitors may be assigned, and the impact of the t2me-window—the 
lag between the time when a monitor begins the registration process and the time 
when it actually begins receiving data. 


Position of a Monitor in the Monitor Chain 


Since a monitor chain may be composed of several device monitors, the position 
of a monitor within that chain takes on significance. ‘The first monitor in the chain 
receives the data records first. When the first monitor writes to its output buffer, 
the monitor dispatcher moves this data into the input buffer of the second device 
monitor, and so on, until the last monitor in the chain is reached. Each monitor 
has control over the data records that monitors further along the chain receive. 
The last monitor has direct control over the data records that are placed in the API 
data buffer. The first monitor also has an effect on what finally appears in the API 
buffer, but the information it passes back to the data stream may be modified by 
subsequent device monitors. It is important to keep in mind that any changes 
made to the data stream by a device driver are passed onto subsequent device 
monitors. For example if the first monitor chain “swallows” a character, no other 
monitor in that chain will receive that character. If the first monitor in the chain 
converts lowercase characters into uppercase, and a monitor further along the 
chain is supposed trap the occurrence of a lowercase “a,” it will be unable to do so. 
The order of these two monitors should be reversed for both operations to be 
performed correctly. 

A device monitor that only monitors for certain keystroke sequences or mouse 
events can be placed anywhere in the monitor chain, as long as an earlier monitor 
does not remove or modify the event sequences the monitor is waiting for (or add 
spurious events to the data stream). 

For some purposes the placement of the monitor becomes crucial. For 
example, if a print spooler is to redirect printer output from the local printer to 
the network printer it should be the last monitor in the monitor chain. This is the 
best position in which to intercept all local output and place it into the buffer of 
the network printer instead of the buffer of the local printer. 

But suppose an application wants to provide translation of the IBM printer 
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control codes into another printer’s codes. This monitor should be placed in the 
first position. This insures that all data sent to the printer will be filtered and 
translated accordingly before it is sent to other monitors and eventually to the 
printer itself. 

The position of a device monitor in the monitor chain is determined at 
registration time. The DosMonReg function allows a device monitor to register 
in the first position, the last position, or the next available position in the chain. 

If a monitor asks to register in the first position, OS/2 places it at the head of 
the monitor chain unless another monitor has already registered in the first 
position. If the first position is already occupied, the monitor is registered in the 
second position. If the second position is occuppied the monitor is placed in the 
third position, and so on, for n monitors that ask to be first. 

The same rule applies to those monitors which request to be last. The first 
monitor which requests the last position gets the last position. The next monitor 
that asks to be last gets the next to the last position, etc. 

Monitors which ask for the next available position are placed right after the 
monitors that requested to be first, and before those monitors that requested to be 
last. 
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Figure 20.3 First monitor request processing. 


Last-n 
position in 
monitor 
chain 


Last 
registered 


as 0 


nth 
registered 
as LAST 


Figure 20.4 Last monitor request processing. 
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Figure 20.5 Next position request processing. 
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Device Driver Data Stream 


The keyboard and mouse drivers define a different data stream for each screen 
group created by the Session Manager. The parallel printer driver only defines two 
data streams, one for the data sent to the printer and the other for printer control. 
Calling the function DosMonReg only registers a monitor for a single data stream, 
so a separate thread must be dedicated to monitoring each data stream. Because 
the keyboard and mouse drivers maintain a separate data stream for each session, 
a separate device monitor must be implemented for each session. 

Although OS/2 supports a maximum of 16 screen groups, device monitors can 
only be installed for sessions 4-15 (those available to OS/2 applications). Sessions 
Q through 3 are used by OS/2: 3 is used for detached processes, 2 is for the 
compatability box, 1 is for the Session Manager, and 0 is for the OS/2 kernel. 
Installing a monitor for these reserved sessions may cause the system to crash. 


Data Buffers and Data Records Received by the Monitor 


A registered monitor (via DosMonReg) must provide an input and an output 
buffer for use in conjunction with the monitor dispatcher. These buffers must be 
the same length as the data records that are passed along the particular data stream 
plus an additional 20 bytes of buffer space used by the monitor dispatcher for data 
record processing. The private buffer used by the device monitor when it retrieves 
the data record (via DosMonRead) should be the length of the data record passed 
on the data stream plus 2 bytes. The memory used by these two buffers should be 
on the same data segment and should not overlap. 

Once the monitor is registered it cannot directly maniplulate the contents of 
these buffers. These buffers are considered as belonging to the monitor dis- 
patcher. The monitor must use DosMonRead to retrieve data from the input 
buffer and DosMonWrite to write data to the output buffer. Under no circum- 
stances should it use any other functions to read or write to these buffers. 

The format of the input and output buffer is as follows: 
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The length of the data record for the keyboard device driver is 12 bytes, for the 
mouse it is 10 bytes, and for the parallel printer it is 3 bytes. Even though 
DosMonkReg allows the monitor to set up larger (up to 32K) input and output 
buffers, any size larger than the size of the data record plus 20 bytes is not 
recommended. Any buffer size larger than this slows down the data transfer rate 
between monitors. 

When a device monitor retrieves a data record with a DosMonRead, it receives 
a buffer containing both the monitor flag and the data record. The monitor flag is 
used to indicate the type of data record the monitor is receiving. The monitor flag 
is an unsigned or a WORD (2-byte) bit-masked value with the following meanings: 
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These bits identify the type of data record being passed through the data stream. 
The programmer should recognize that a device monitor will be exposed to data 
other than just that meant for an application. It will also be passed data records 
used by the device driver for management purposes. A data record with the open 
bit set is used to notify the device subsystem that the device is opened. A datarecord 
with the close bit set notifies the device subsystem that the device is closed. The 
device monitor should ignore these types of data record and simply place them 
back into the data stream. A device monitor should never swallow data records with 
the open or the close bit set from the data stream. 

A data record with the flush bit set is called the flush record. The flush record 
notifies the device subsystem to ignore all data records currently in the API buffer. 
The device monitor uses the flush record to reset its own internal data buffer. The 
device subsystem will correspondingly flush the API buffer when it receives the 
flush record. The flush record, therefore, is very important and must be passed to 
all monitors in the chain and to the API buffer. The flush record should be left 
alone and never be taken out of the data stream by a device monitor. 

If the flush record is swallowed by the device monitor, the subsystem will send 
the device driver a “buffer full” signal because there will be old data records in an 
API buffer which was supposed to be clear. When a keyboard monitor consumes 
the flush record, and the API buffer fills up, the keyboard driver generates a “beep” 
sound. 

So far we have only discussed the possible meanings of the least significant byte 
of the monitor flag. The form and content of the data record and the upper byte 
of the monitor flag are device-driver dependent values which will be presented 
separately for each device driver. 


Keyboard Monitor Data Record 


For every keystroke entered at the keyboard, two data packets are generated by 
the device driver. One packet is sent when the key is pressed (key make) and the 
second is sent when the key is released (key break). Each packet, in turn, is placed 
in the input buffer of the keyboard monitor. Whenever a keyboard monitor issues 
DosMonRead, a data record of the following format is retrieved from the input 
buffer. 
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The input and output buffers of a keyboard monitor should include a 2-byte 
value specifying the length of the structure, an 18-byte block for the use of the 
monitor dispatcher, 2 bytes for the monitor flags, and the above data record block. 

Even though we have explained the general significance of the bits in the 
monitor flag, the handling of the monitor flag by a keyboard monitor raises some 
points that need to be addressed. The monitor flag for a keyboard monitor 1s a bit- 
mask value with the following possible bit values: 
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The character data packet block contains the ASCII code, the scan code, the 
DBCS status, the DBCS shift status, and the shift state of the keystroke plus the time 
stamp in milliseconds when the character was received by the keyboard driver. The 
meaning of this data packet was explained in the section discussing function 
KbdCharIn in Chapter 14. This packet is the same as the packet received by 
KbdCharIn. 

The KbdDDFlag is used by the device monitor to further determine the type of 
character data packet received. This flag is used by the device subsystem, and is not 
passed to an OS/2 application using API functions. The KbdDDFlag is a bit-mask 
value in which each set bit signifies the presence of conditions. The possible values 
are. 
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Not all data packets are sent to the keyboard monitor. Certain keystroke 
sequences require immediate action from the keyboard driver such as the reboot 
key, or the dump key. Certain other keystrokes are translated by the device driver 
before they reach the monitor (chain). Other keystrokes are first passed to the 
keyboard monitor, and acted on afterwords (i.e., Cntrl-break or Cntrl-C, which 
terminates the currently running process). 

Tables 20.1 through 20.3 list the keystroke sequences handled by the device 
ariver before being sent to the monitor, or passed through the monitor chain, then 
acted on afterward. 


" If the previous key is an accented key, and the next keystroke does not use the accent, the keyboard driver first 
will insert a data packet containing the accented character. This data packet will have this bit set and the upper 
byte of the monitor flag value would be set to 0 which indicates that the key was not generated by the keyboard 
hardware, but is generated by the driver. Following this packet is the packet containing the actual keystroke with 
the accent bit off. 
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Keystrokes Meaning 

Ctrl-Alt-Del Reboot system 

Ctrl-Alt-NumLock Press twice to perform system dump 
Pause Pause System 

Ctrl-S Pause System 

Cntrl-Esc & Session Manager Hot Keys 

Alt-Esc 


Table 20.1 Key sequences not passed to a keyboard monitor. 


Scan Code 


UE 


02H 


03H 


04H 


Meaning 


ACK—keyboard acknowledge scan code. The PC AT keyboard 
will set this value when it receives a hardware scan code of FAH. 


Secondary Key Prefix—generates only by the enhanced key- 
board to notify the driver that the scan code of the next data 
packet will be one of the secondary keys that exists only on the 
enhanced keyboard (1.e., Fl] or F12 etc.). Secondary keys have 
hardware scan codes ranging from EOH to E1H. 


KBD Overrun—generated to indicate an overrun. This value will 
be generated when a hardware scan code of FFH is received. 


Resend—aindicates a “resend” request from the keyboard. 


No data packets for these scan codes will appear in the KIB (APIBUFFER). 


Table 20.2 Scan Codes handled by the keyboard driver before being passed to 
the keyboard monitor. 











Scan Code 


07H 


11H 


12H 


13H 


14H 


15 


16H 


17H-2FH 
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Meaning 


Shift Key—this scan code changes the shift status fields. There 


_will be no define character record for the code and it will not be 


placed in the KIB. 
Cntrl-Break—indicates that the cntrl-break was entered by the 
user. The device driver will send a SIGBREAK signal to the 


current PYrOcess. 


Cntrl-C—generated only in cooked mode, this will be translated 
by the driver as a termination indication from the user. 


PrtScr—indicates a print-screen request. Keyboard driver will 
notify the Session Manager to perform a print-screen function. 
Print Echo—(Ctrl-PrtScr) , keyboard driver will notify the Session 


Manager to toggle the print echo mode. 


Pseudo Print Echo—(Ctrl-P), in cooked mode the driver will 
toggle print echo mode. 


Print Flush—(Ctrl-Alt-PrtScr). 


Reserved—must be zero. 


These scan codes will first be passed through the monitor chain, then acted on 
by the device driver. 


Table 21.3 Scan Codes Handled by the Driver before arrival to the KIB 


(API Buffer) 
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Parallel Printer Data Record 


Two data streams are defined by the device driver, one for the data sent to the 
printer by the application (index = 1)? and the other for printer control or code 
pages functions (zndex = 2). 

The format of the data packet passed through the character data stream is as 
follows: 





Mouse Data Record 


For each mouse event, the mouse driver sends a data packet to the data stream. 
The data packet sent by the mouse driver has the following structure: 


2 DosMonReg requires an index parameter that identifies the data stream for which the device monitor is being 
registered. An index number | registers the calling thread for monitoring the character data stream. An index 
number 2 registers for the printer control and code page data stream used by the parallel printer driver. 
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Device Monitor Registration’s Time Window 


The registration of a device monitor is a complicated process which takes some 
time. It is possible that information may pass through the data stream before the 
device driver has been registered. These data packets would be placed in the API 
buffer. A device monitor can recover this information by reading the API buffer 
with an API data request function. However, if some other process reads the API 
buffer beforehand, then there is no way for the device monitor to recover those 
data packets. It is not possible for a device monitor to read the buffer maintained 
for the parallel printer. 

Reading the API buffer is very helpful if a device monitor needs to capture type- 
ahead characters which occurred during the time it was trying to register. For 
example, if a screen group has just started and the first process to be launched is 
the keyboard monitor, the user might type some characters before the monitor has 
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completed the registration process. The monitor can still retrieve these type- 
ahead data packets using KbdCharIn to read the KIB. Since there are no other 
processes running that could remove these data packets, the monitor will defi- - 
nitely be able to retrieve all keystrokes entered before and during the time of its 


registration. 


Monitor Functions 


Monitor Functions 


DosMonOpen 


DosMonReg 


DosMonRead 


DosMonWrite 


DosMonClose 


Meanings 


Establishes access to the data stream defined by the 
device driver. 


Registers a device monitor with the monitor dispatcher 
and provides the input and output buffer used by the 
monitor dispatcher for data transfer. 


Reads a data record placed in the input buffer by the 
monitor dispatcher. 


Writes the data record back to the output buffer. 


Closes the device monitor and unregisters the monitor 
with the monitor dispatcher. 


Table 20.4 Monitor functions and their meanings. 


Here is the pseudo-code for a device monitor: 


handle = DosMonOpen() 
DosMonReg (handle, input_buffer, output_buffer) 


WHILE not end 


BEGIN 


data_record <— DosMonRead () 


/* get data record and modify 
or leave At intact */ 
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IF data_record is to be sent back to the data 


stream 
DosMonWrite (data record) 
ENDIF 
END WHILE 
DosMonClose() /* close the monitor */ 


DosMonOpen: Request Access to Data Stream 


DosMonOpen allows the calling thread to request access to a data stream 
defined by a character device driver. The driver is identified by a device name 
specified in parameter DeuName. DosMonOpen returns a device handle, which 
must be used with DosMonReg to register the device monitor. 

The following devices allow for device monitors: 


Device Name 
Keyboard KBD$ 
Mouse MOUSE 
Parallel Printer LPT1 - 3 


Once a device is opened by DosMonOpen and a device handle is obtained, the 
device handle can be used by multiple DosMonReg calls to register multiple 
monitors with the device. However, DosMonClose closes all monitors registered 
for a particular device handle. 


DosMonOpen (DevName, Handle) 


char far *DevName; /* ASCIIZ string containing the device 
name */ 
unsigned far *Handle; /* variable where the handle will be 


returned */ 
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DosMonReg: Registers Device Monitor 


DosMonReg registers the calling thread as a device monitor for a particular data 
stream defined by the device driver. The thread must set up the input and output 
buffers by specifying two pointers to two data blocks, /Bufferand OBuffer. DosMon- 
Reg also allows the calling thread to specify which data stream it wishes to monitor, 
and its position within the monitor chain. 

The size of the buffers must be at least as large as the data packet generated by 
the driver, plus 20 bytes reserved for the monitor dispatcher. Input and output 
buffers are discussed in greater detail on page 788. The pointers, /Buffer and 
OBuffer should be saved by the thread because they will be used later with the 
functions DosMonRead and DosMonWrite. 

The minimum size of the I/O buffers for each supported device are as follows: 


Device Minimum Size 
KBD$ 20 bytes + 14 byte data packet 
MOUSE 20 bytes + 12 byte data packet 


LPTI - LPT3 20 bytes + 5 byte data packet 


The parameter /ndex identifies the data stream which the the device monitor 
wishes to monitor. The keyboard and mouse drivers define a separate data stream 
for every screen group created by the Session Manager. The index number of a 
keyboard data stream has the same value as the session number. Mouse driver 
index numbers are the same as the screen group index. The parallel printer driver, 
however, defines only two data streams: one for data sent to the parallel port (/ndex 
= 1) and the other for printer control, code page and font support (/ndex = 2). An 
index number of -1 specified by a mouse or keyboard monitor indicates that it 
wishes to monitor the data stream for the current screen group. [The nature of the 
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data stream specified by the index number is discussed in detail earlier in the 
chapter. The possible values for /ndex are: 





The parameter Posflag defines the position of the monitor on the data stream. 
The significance of the position of a monitor is discussed ealier in this chapter. The 
possible values for Posflag are: 





DosMonReg (Handle, IBuffer, OBuffer, Posflag, Index) 


unsigned Handle; /* handle to the device, returned from 
DosMonOpen */ 

char far *IBuffer; /* data block defining the input buffer */ 

char far *OBuffer; /* data block defining the output 


buffer */ 
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unsigned Posflag; /* the preferred position of the device 
monitor */ 

unsigned Index; /* index number defining the data 
stream */ 





DosMonRead 


Once a monitor is registered for a data stream, any data packets sent from the 
device driver can be read from the input buffer using function DosMonRead. The 
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function simply moves the data packet from the input buffer, /Bu/ffer, to another 
buffer, DataBuffer, defined by the calling thread. Databufferis a pointer to a data 
block private to the device monitor and /Bufferis the pointer to the input buffer 
registered earlier with DosMonReg. 

Only aregistered input buffer can be read from. OS/2 returns the error “Error_ 
Mon_Invalid_Parms,” if the monitor has not been registered or the registration 
has not been completed. If the monitor has been closed by a DosMonClose, an 
error “Error_Mon_Buffer_Empty” is returned. 

DosMonRead can be specified to wait until a data packet is available or not 
return immediately if the input buffer is empty. The wait option is defined by 
WaitFlag. ‘The possible values for WaiiFlag are: 





The number of bytes to be read from the input buffer is defined by Bytecnt. The 
size of DataBuffer should be at least the same length as Bytecnt. Once the data 
packet is moved to DataBuffer, OS/2 places the actual length of the data packet read 
from the input buffer into the variable Bytecnt. This value should be set as the size 
of the data packet, because only the transfer of an entire data packet is allowed, and 
the reading of a partial record is not possible. 


DosMonRead (IBuffer, WaitFlag, DataBuffer, Bytecnt) 


char far *IBuffer; /* pointer to a registered input buffer */ 
unsigned WaitFlag; /* wait option */ 
char far *DataBuffer; /* pointer to a data block to where the 


data packet will be moved */ 


unsigned far *Bytecnt; /* on entry this equals the number of 
bytes to be read; on return this 
specifies the number of bytes actually 
read */ 
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DosMonWrite 


DosMonRead moves a data packet from the input buffer to an internal data 
block. DosMonWrite moves a data packet from an internal buffer to the registered 
output buffer of the device monitor. DosMonWrite returns similiar errors to 
DosMonRead: “Error_Mon_Invalid_Parms,” if the output buffer has not been 
registered and “Error_Not_Enough_Memory,” if the monitor has been closed. 

DosMonRead expects the pointer to the registered output buffer ( OBu/ffer) , the 
pointer to the internal data buffer (DataBuffer) from which the data packet will be 
moved, and the number of bytes to be output ( Byltecni). An entire data packet must 
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be written to the output buffer. Therefore Bytecni should simply be set to the size 
of the data packet. The size of the data packet should never be larger than the size 
of the input buffer. 


DosMonWrite (OBuffer, DataBuffer, Bytecnt) 


char far *OBuffer; /* pointer to the registered output 
buffer */ 

char far *DataBuffer; /* pointer to a data packet to be 
output */ 

unsigned far *Bytecnt; /* the number of bytes to be read or 


the size of the packet */ 





DosMonClose: Close Monitor 


DosMonClose disassociates a device handle from a particular device. When this 
function is called, all monitors registered with the device handle will be closed as 
well. This function should be used to de-register all device monitors associated 
with a device handle. It cannot be used to selectively deregister device monitors 
one ata time. This is the only shortcoming in OS/2 support for device monitors. 
Once a device handle is obtained via DosMonOpen, several monitors can be 
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registerd with one device handle via DosMonReg. When DosMonClose is issued 
for the device handle, all device monitors will be deregistered. 

DosMonClose should be issued after the completion of all DosMonRead and 
DosMonWrite calls, otherwise errors will be returned. 


DosMonClose (DevHandle) 


unsigned DevHandle; /* device handle obtained via 
DosMonOpen */ 





Example: make file (MONITOR) 


CFLAGS= -GZ -Zi -OQd -Lp -Zec 
LIBS = doscalis.lib 


monitor.obj: monitor.c 
cl -e S(CFLAGS) monitor.c 


monitor.exe: monitor.obj 
link (eo monator, monitor. <6{ LIBS) ;: 


moen.op7s  Men.e 
cl. =«c¢ S{(GFLAGS) itmon.c 


mon.exe: mon.obj 
link /co mon,mon,,S(LIBS),: 


Example: Source file (MONITOR.C) 
/* MONITOR.C 


This program demonstrates how to use the monitor API functions. 
The program should be run as a detached process. The program 
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simply registers a monitor to the current keyboard data stream, 
captures all data packets or all keyboard entries on the stream, 
and terminates when the user presses Cntrl-Alt-Q. 


Another program, MON.C, simply starts this program as a detached 
process. 


Notes: 


a 


This program only registers a keyboard monitor for the 
current screen group, and not for all screen groups. The 
same programming method is used to set up a monitor for 
each possible keyboard session. 


When registering a monitor for all keyboard sessions, 
there is a reduction in performance of 0S/2 in displaying 
the keystrokes (from the time a key is pressed and the 
time it is displayed). This problem can be solved if each 
monitor is frunhine as a time-critical thread. 


include “doscalls.h” 
include “subcalls.h” 


include <malloc.h> 
include <dos.h> 


#tdefine VP_NOWAIT 0x0000 /* constants for VIOPOPUP */ 
#tdefine VP_WAIT Ox0001 /* wait or no wait option */ 
4#tdefine VP_OPAQUE O0x0000 /* clear the ecrean */ 
d#edefine VP_TRANSPARENT 0x0002 /* do not clear the screen 


if text moda */ 


4Hdefine BUFFER SIZE 64 

#tdefine NO_PREFERENCE Ox0000 /* positional reference of 
the monitor */ 

4tdefine FIRST 0x0001 


4tdefine LAST 0x0002 
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define WAIT 0x0000 /* wait option for DosMonRead */ 
ftdefine NOWAIT 0x0001 

define NOTSHARED 0 

#tdefine CNTRL 0x0004 /* either cntrl key is down */ 
define ALT 0x0008 /* either Alt key is down */ 
#tdefine K_Q 0x0010 /* scan code for the kay Q */ 
4define RELEASE Ox40 /* release key */ 

define VP_NOWAIT 0x0000 /* constants for VIOPOPUP */ 
#tdefine VP_WAIT 0x0001 /* wait or no wait option */ 
define VP_OPAQUE Ox0000 /* clear the screen */ 


+#define VP_TRANSPARENT 0x0002 /* do not clear the screen if 
text mode */ 


+#define VERT 
+#define HORZ 
define UPRT 
+#define LWLF 
4#tdefine LWRT 
#tdefine UPLF 


/* definition for drawing box */ 


i 4 Go ND FR Se 


struct KBDPACKET { 
unsigned MonFlag; 
struct KeyData data: (* define in DOSCALLS.h */ 
unsigned KbdDDFlags; 


struct MONBUF { 
unsigned buflen; 
char reserved[18] ; 
etruct KBDPACKET data_record; 


struct LOUTInfe { 








unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 


struct GDTInfo 


ys 


long 
long 
char 
char 
char 
char 
unsigned 
unsigned 
char 
char 
unsigned 
char 
char 
enar 
char 
char 
char 
char 
char 
unsigned 
char 
char 
unsigned 
unsigned 
unsigned 
char 


Current_PID: 
Parent _PID; 

Preecy Current 3 

LLD Current 5 
SserGroup_Current; 
subScrGroup; 
Foreground_Flag; 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 


current PID */ 

parent PID */ 

currant PRTY */ 

eurrent thread ID */ 
current screen group # */ 
Sub-Screen group # */ 
whether the thread is in 


foreground */ 


/* etructure for GDT */ 


time; 

milligeconds: 

hours: 

minutes; 

seconds; 

hundreths; 

timezone; 

timer interval: 

day; 

month; 

year; 

day_of_week; 
major_version; 

minor version; 

revision number: 
current_screen_group; 
max_num_of_screengrps; 
huge_selector_shift_count; 
protect_mode_indicator; 
foreground_process_id; 
dynamic_variation_flag; 
maxwait; 
minimum_timeslice; 
maximum _timeslice; 

boot _drive: 
reserved [32 | : 


void far monitor(): /* monitor thread 


si 
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void errmsg(); /* display error message */ 
void box(): /* display box */ 
void WriteScreen(); /* rite data te ecréaen */ 
unsigned lstrlen(); /* far etrien tumetion */ 
unsigned quit = 0; 
srruct LOT late tar *Ldc: /* polnter to the LOT */ 
struct GOUTInte far *edrs /* and the GBT */ 
main() 
{ 

unsigned selector: /* seleetor of the sesment*/ 


unsigned ret; 


unsigned i; 
unsigned thread_id; 


unsigned gdt_selector, ldt_selector; 
char *Stack: /* stack segment for monitor 
thragd */ 


DOSGETINFOSEG(&gdt_selector, &ldt_selector); 
ldt = (erruet LDTInio far *)t (long) lat. selector << 16); 
edt = (struct GDTIinfo far *)(llong)edt.selecter << 16); 


/* get the priority of the primary thread to be medium */ 
/* priority: time eritical. and tis *? 


DOSSETPRIVY(2, 3, 1S, idt-22T1To Current) ; 


if ((Stack = malloc(1024)) == 0) 
esrrmee( {char far *)"\nmelloe|): ter euecessiul” 0); 


/* ereate a the monitor 
Lnraad, *7 
Stackt=1024: 
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if (ret = DOSCREATETHREAD (monitor, 
(unsigned far *) &thread_id, 
iehar far *)Stack) } 
errmsg ((char far *)”DosCreateThread failed.”, 
ret); 


duit = 
while (!quit) 
DOSSLEEP(1OGOL, : 


errmse((echar far *)”"Cntrl-Alt-Q is pressed” ,0); 


DOSEXIT(1, 1); 


void far monitor) 


{ 
unsigned MonHandle; 
char IBuffer[BUFFER SIZE], OBuffer[BUFFER SIZE]; 
struct KBDPACKET keybuf; /* keyboard data buffer */ 


struct MONBUF *p; 
unsigned ByteCnt; 


unsigned ret; 
if (ret = DOSMONOPEN(“KBDS”, (unsigned far *) &MonHand1le) ) 
errmsg((char far *)”DosMonOpen failed.”, ret); 


Oo = (struct MONBUF *) IBuffer: 
p-7buflen = BUFFER_SIZE; 


p = (struct MONBUF *) OBuffer; 
p-7buflen = BUPFER_ SIZE: 
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/* determine the session ID of the current session */ 


if (ret = DOSMONREG(MonHandle, /* register the monitor */ 
(char far *)IButfer, 
(char far *)OButfer, 


LAST, 
gdt->current_screen_group) ) 
errmsg((char far *)”DosMonReg failed.”, ret); 


while (1) { 
ByteCnt = sizeof (keybuf) ; 


/* read the keyboard packet */ 


DOSMONREAD( (char far *)IBuffer, WAIT, (char far 
*) &keybuf, 


(unsigned far *)&ByteCnt) ; 


/* at this point we have the packet, we can examine/alter the 
contents of the packet, then write the packet back to the 
output buffer “/ 


/* in this example, we will determine whether a Cntrl1-Alt-Q was 
pressed then display a message on the screen then quit */ 


if (keybuf.data.char_code == 0 && 
keybuf.data.scan_code == K_Q 
&& (keybuf.data.shift_state & (CNTRL | ALT))) { 
dijak = 13 
break; 


} 
DOSMONWRITE((char far *)OBuffer, (char far 
*) &keybuf,ByteCnt) ; 


} 
DOSMONCLOSE(MonHandle) ; 
DOSEXIT(0,0): 


unsigned lstrlen(s) /* far strlen */ 
char tax. “2; 











Character Device Monitors 819 


Chat tar "ic; 
unsigned i=0; 


= as 

woile (*t+tt != ‘\07) 
= Wg eae ia 

return(i}: 


void box(x,y,xl,yl) /* dieplay box. */ 
unsigned x,y,xl,yl; 


{ 
static char border[6|] ={* \eB3’*.*\xC4'.°’ \eBR’,* \xC0';’ 
\eD9', * \xeDA* HT: 


4Tit 2% 
int row. column: 


VIOGETCURPOS (&row, &column,0O); 


VIOWRTNCHAR (&border [HORZ] , (yl-y-1).x,yt1,0); . 
VIOWRTNCHAR (&border [HORZ] , (yl-y-1),x1,yt+1,0); 


for (a=eflsd < sleds) -{ 
VIOWRTNCHAR (&border [VERT] ,1,i,y,0); 
VIOWRTNCHAR (&border [VERT] ,1,i,y1,0); 


VIOWRTNCHAR (&border[UPRT],1,x,yl1,0); 
VIOWRTNCHAR (&border[LWRT],1,xl,yl,0); 
VIOWRTNCHAR (&border [UPLF],1,x,y,0); 
VIOWRTNCHAR (&border[LWLF] ,1,xl,y,0); 


VIOSETCURPOS (row,column,0); /* move the cursor back to */ 
/* orieinal postition */ 


} 


void WriteScreen(s,x,y) /* write string to the screen */ 


char far *s* 
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unsigned x,y; 
{ 
VIQWRTICHARSTR(s,lstrlen(s), x,y, 0); 


void errmsg(s, errcode) /* display a pop-up message */ 
char tar “se 
unsigned errcode; 
{ 
gchar @[2 |: 


unsigned option; 
unsigned y; 


efo| = * *s i* @ell te replicate i6 4 blank */ 
e[l] = 7: /* with normal attributes */ 
option= VP_WAIT | VP_TRANSPARENT ; /* clear the screen */ 
/* and wait uwatil 
nep-up =/ 


if (VIOPOPUP (&0ption,0) ) 
DOSEXIT(1,1): 


y = 20+lstrilen(te)t+2: 


/* elear the box before writing at */ 
VIOSCROLGLUP (10, 3,15,%7,5, (ohare far *)a,0): 


box(10,5,15,4¥}% 


Weitesereen(s,11,6) : 
WriteScreen((char far *)”Detached process is terminated.” 
eset: 
DOSSLEEP (5000L) ; 
VIOENDPOPUP (0) ; 
if (erroeodé) /* 4f error code > 0 then exit */ 
DOSBXET (1,1) 
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Device Monitors and DOS TSRs 


A device monitor should not be used as a means of developing TSR programs 
which pop-up in the middle of the execution of another application. TSRs are no 
longer necessary under OS/2 due to the availability of multitasking. The user no 
longer need to remember which keystroke sequence is associated with each TSR. 
The user only needs to know the hot key sequence defined by the Session Manager 
to switch between applications. During the time of a pop-up OS/2 session 
switching is disabled. The device monitor/pop-up combination should not be 
used to supplement the OS/2 session switching facilities, because they wind up not 
supplementing them but interfering with them. TSR type functionality is a good 
way to simulate multitasking under DOS, but under OS/2 it is obsolete. Using the 
monitor/pop-up combination to approximate a TSR only creates confusion for 
the user. 

A device monitor should only be used to allow a background application to 
receive input from the user and to temporarily pop-up. This facility could be used 
to allow the user to check the status of a background process or application. Most 
device monitors should simply filter the data stream and not pop-up at all, unless 
it is to report the occurrence of an error on their part. We feel that the use of pop- 
ups should be kept to a minimum because of the additional processing required 
to handle them, especially when used in conjunction with graphics based environ- 
ments such as the Presentation Manager. 


Chapter 21 


_ 
DOS and OS/2 


must now decide what to do with their existing DOS applications. In the 

simplest case the developer will simply want his old application to execute 
in the compatability box. For most programs this will require only a few changes. 
The developer can also choose to convert her application to run in the OS/2 en- 
vironment. For well behaved programs (i.e., programs which do not use any 
memory segments not explicitly allocated by the linker or compiler, and which do 
not access memory beyond the bounds of these segments) conversion is a matter 
of changing all the DOS and BIOS calls (INT 21H, INT 15H, INT 10H, etc.) to 
OS/2 API calls. Converting DOS and BIOS calls to OS/2 API function calls is not 
too difficult, since most of the DOS and BIOS calls have corresponding API 
functions. Developers who make this effort will be rewarded with applications 
which can address memory up to the OS/2 virtual memory limit of 1 gigabyte (this 
results in a marked increase in performance for programs which heretofore had 
to rely on overlays to fit within the 640K boundary) and which can receive 
processor cycles while in the background. However, if a program uses memory 
wantonly (addresses unallocated memory or memory outside of allocated seg- 
ments, or depends on any physical relationship between segment locations in 
memory) the conversion process will entail redesigning its memory usage to fall 
into line with the protected mode guidelines. Such an application will probably 
run in the compatability box without modification. 

Many developers will want to completely restructure their applications to take 
advantage of the new OS/2 features, such as multitasking, interprocess communi- 
cation, message services, and dynamic linking. Such an effort will require a 
complete redesign of the application with a lot of new code. Because of the 
complexity involved in this last step many developers have decided to convert to 
OS/2 in two stages. First they port their DOS application to OS/2, then later they 
redesign it to take full advantage of the OS/2 multiprogramming features. 


\\/ e have learned all the features of OS/2. Many application developers 
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Another important variable affecting the conversion effort is the language in 
which the application being converted was written. Programs written in high-level 
languages will generally be easier to convert than MASM programs because of 
differences in the 8088 processor and the 80286 processor running in protected 
mode. Most 8088 instructions will work in the 80286 protected mode, however 
there are subtle differences in design philosophy which will require minor changes 
to assembly codes. 

This chapter explains the issues and problems a conversion effort must take into 
account. The chapter will explain: 


= the rules for converting DOS interrupt calls to OS/2 API calls; 
*= converting DOS programs written in MASM to an OS/2 environment; 


" differences between compatability box and FAPI applications. 


Conversion of High-Level Language Programs 


Cis probably the language of choice for programming under OS/2. Most API 
functions were designed with C function calls in mind. If your application was 
written in C, and the program was designed following the rules for a well behaved 
program, conversion to OS/2 is a matter of changing the DOS calls to API calls 
wherever necessary, recompiling the code with the OS/2 C compiler, and finally 
linking the program with the OS/2 libraries. All C run-time library functions have 
been re-written to take advantage of OS/2 API calls. 

Conversion from other high-level languages is held up for the moment bya lack 
of compilers. These should be available from Microsoft, IBM, and other vendors 
soon. In most cases the conversion process should be similar to that for the C 
language. Ifa developer cannot wait she can always convert her application to C. 


Conversion to API Calls 


Before we can convert a DOS or BIOS call to an API call we need to understand 
its calling convention. | 


OS/2 API Interface Conventions 


= Parameters are placed on the stack (SS:SP). If the parameter is an address, 
it must be in the form of selector:offset. Both selector and offset must be 
placed on the stack. 
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Each API function will remove these parameters from the stack. There is 
no need for the calling program to concern itself with this. 


= API Functions are accessed by FAR calls. 


# API function return an error code in the AX register. A zero value indicates 
a successful call. 


Appendex B lists each DOS interrupt call and its OS/2 counterpart. Please use 
this list for your conversion. Most OS/2 functions were designed to accept the 
same parameters as the corresponding DOS or BIOS functions. ‘Therefore 
conversion is merely the tedious task of changing the format of each DOS INT 
function, one at a time. 


Converting 8088 Assembly to 80286 Assembly 


Most 8088/8086 instructions will run in the 80286 protected mode. The major 
problem in an assembly language conversion lies in the differences in writing 
pregrams for the 80286 protected mode and the 8086. In real mode assembly 
language programmers often take advantage of the lack of protection features to 
make their code more efficient. In protected mode, as described in earlier 
chapters, the code and data segments of one process are protected from being 
interfered with by any other process. Any attempt by a thread to execute code or 
access data beyond that explicitly allocated to it (contained within its LDT) 
generates an exception. This difference creates a lot of problems when converting 
cleverly written assembler programs to OS/2. 

The following popular real mode assembly language programming techniques 
are absolutely not allowed under protected mode: 


Segment Address Differences 


A program cannot assume anything about the actual mapping of an address 
in physical memory based on the selector:offset as in real-mode. In the 8086, 
the segment represents the high order bits of the actual address in physical 
memory. In the 80286 protected mode this relationship is no longer valid. 


= A program cannot depend on any segment overlap based on segment 
registers. [he segment register of the 8086 contains a displacement value, 
but in the 80286, the segment registers in the 80286 are simply an index 
value on the LDT. 


= All values placed in the segment registers must be valid selectors to memory 
segments. They must be the actual index values on the LDT. The segment 
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registers cannot be used as temporary storage. The assembly program 
therefore must only use segment values that it obtains from the linker, 
from the operating system, or from another function. 


=Programs cannot assume that certain memory segments are contiguous. All 


memory segments are addressable up to 64K. In order to address the next 
segment, the program cannot simply change the segment address because 
this new value might not point to the correct segment. Most of the time the 
new value will be invalid. For huge data segments, use function Dos- 
GetHugeShift. 


Programs cannot address beyond the pre-allocated size of asegment. This 
will generate an exception. In real-mode, the program might not crash if 
it tries to access data belonging to the operating system or other programs, 
but in protected mode, the program will be stopped by the operating 
system. 


Programs cannot place code and data in the same segment. This is the 
normal convention for DOS .COM files. 


Data segments can never be loaded into the CS register. Code segments can 
only be loaded into the DS register if they are readable. 


Code segments are no longer modifiable during run-time. 


The 8086 has 20 address lines and the 80286 has 24 address lines. 
Therefore, assembly programs cannot depend on a wrap-around segment 
offset. The 8086 sets up physical memory addresses by multiplying the 
segment address by 16 then adding this value to segment offset. Any 
overflow is ignored by the 8086, making it possible to address lower 
memory by using very large segment and offset values. For example, the 
physical address of 0000:20 can be referenced using a very large address of 
FFFO0:30. Under protected mode this is no longer possible. 


Interupts 


OS/2 application programs cannot issue or trap interrupts. Nor can they 
service hardware interrupts. Only device drivers are allowed to service 
interrupts under OS/2. 


*" Do notuse CLI. Only IOPL segment or device drivers which run ata higher 


privilege level can issue CLI. A protection trap will be generated by 
OS/2 if a CLI is issued without its permission. 


The IRET function does not restore the previous value for the IFLG flag. 
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Instruction Differences 


= Do not use the PUSH SP instruction. The 8086 pushes the value that SP will 
contain after the PUSH instruction is executed. The 80286 pushes the 
current value of SP before the PUSH instruction is executed. 


= Shift counts greater than 31 cannot be used. 


= Do not use redundant prefix bytes. The 80286 has a instruction length limit 
of 10 bytes. 


=" Undefined opcodes cannot be used. 


=" Do not depend on CPU speed for any reason. Different CPUs have different 
speeds. In addition, OS/2’s multitasking system does not allow a program 
to directly monitor the CPU clock. OS/2 timer services, or monitoring the 
Global Information should be used for this purpose. 


Flag Registers 


= Do not examine or set the flags registers. The program must use the flag 
instructions to set or test flag registers. The program should not use LAHF 
or SAHF. 


"There are more flags in the 80286. 


= POPF instruction does not work properly in the 80286 protected mode. Use 
the POPFF macro provided by the assembler. This bug sometimes allows 
interrupts to be generated while executing the POPF instruction to restore 
a flag word that that has disabled interrupts. 


Compatability Box and FAPI 


There are differences between applications written to run in the compatability 
box and FAPI applications. Compatability box applications use the old DOS 3.x 
style interface, with certain restrictions and will run on areal mode machine or in 
the compatability box. Family API applications use a subset of the OS/2 API and 
are designed to run in protected mode on OS/2 machines and real mode on 8086/ 
88 machines. 

This section presents the characteristics of each type of application, and the 
differences between them. 
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Compatability Box 


The compatability box is a special OS/2 session which exhibits all of the 
characteristics of the 8088 processor running in its native or protected mode. 
OS/2 only supports one instance of the compatability box session ata time. Within 
this session “unmodified” (with certain exceptions) DOS 3.x programs can be exe- 
cuted. While the compatability box session is in the foreground it is in full control 
of the machine (it can directly access video boards, access all memory under 1 MB, 
etc.). In fact, OS/2 switches the CPU into real mode. Switching the machine from 
real mode to protected mode is simple (a bit in the status word is turned on), but 
switching from protected mode is to real mode is a complicated affair which has 
been compared to “switching off the engine to change gears.” ‘The mode switch 
from protected mode to real mode that occurs when the compatability box session 
is selected into the foreground can take up to a millisecond, and no interrupts can 
be serviced during this time. While the compatability box is in the foreground 
protected mode processes running in background sessions continue to receive 
processor cycles from the OS/2 dispatcher. However, if the compatability box 
session is switched into the background it is “frozen” and receives no processor 
cycles whatsoever. 

Programs running in the compatability box are still bound by the 1 MB 
addressing limit of the 8088. Actually, programs running in the compatability box 
have less memory available to them than an application running on an actual 8088 
machine would have. This is because OS/2 uses a larger portion of low memory 
for its low kernel and device drivers (110 KB). ‘This drawback is alleviated 
somewhat by the fact that programs running in the compatability box can take 
advantage of expanded memory (EMS). 

Many existing DOS applications will run without modification in the compata- 
bility box. All DOS 3.2 interface functions are supported by the compatability box. 
(Int 26H “Direct Write to Disk” only works for removable media, not for hard 
disks). One can consider the compatability box as DOS 3.2 with the SHARE 
command invoked. In addition, most important BIOS calls are supported in the 
compatability box. Table 23.1 shows the extent of this support. 


BIOS Interrupt No. Service Extent of Support 
05H Print Screen Not supported 
10H Video Fully supported 
Lik Equipment Check Fully supported 


12H Memory Size Only returns information 


(continued) 





13H 


14H 


15H 


16H 
17H 
19H 
1AH 


1BH 
1CH 
1DH 
1EH 


1FH 


Diskette 
Hard Disk 


Serial Ports 


Misc. 


Keyboard 
Printer 
Reboot 
Time of Day 


Break 

Timer 

Video Parameters 
Diskette 
Parameters 
Graphics Fonts 
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for compatability box 
Fully supported 

Only functions 01H, 02H, 
OAH, and 15H are 
supported 

Disabled unless the 
SETCOM40 utility is 
invoked 

Functions 87H, 88H, 89H, 
90H, 91H are not supported 
Timer functions 83H, 86H 
are limited to a sensitivity of 32 ms. 
Fully supported 

Fully supported 
Supported 

Functions 02H-07H are 
not supported 

Fully supported 

Fully supported 

Fully Supported 

Only during system 
initializtion 

Fully supported 


Table 21.1 BIOS calls supported in the Compatability Box. 


Directly accessing COM ports from the compatability box involves special 
difficulties. Ordinarily OS/2 hides their existence from compatability box appli- 
cations. This is done to prevent compatability box applications from wreaking 
havoc with background protected mode processes doing COM port I/O. If there 
are no background processes doing COM port I/O, a compatability mode appli- 
cation can directly access a COM port if the command line utility SETC@OM40 is 
issued first (See Appendix A for a complete discussion of the use of this function). 

Several other operations are often performed in real mode that cannot be 
performed in the compatability box. These are: 


" Directly addressing locations in the ROM BIOS. This is because OS/2 first 
handles all BIOS requests in order to insure synchronization with back- 
ground processes before passing them on to the ROM Bios. 
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=" Manipulating the values in the system real-time clock, as this clock is used 
by OS/2 for scheduling. 


*" Compatability box applications should never attempt direct I/O writes to 
system hard files such as an FAT or directory table. Ifa background process 
is also updating the disk at this time the integrity of the disk could be 
jeopardized. In other words, disk utilities should not be implemented in 
the compatability box. 


#® DOS 3.2 network calls are not allowed. 
=" Most undocumented DOS calls will fail, though some may work. 


=" No compatability box program should ever reprogram the disk controller 
or DMA controllers. 


=" Reprogramming the 8259 interrupt vectors is not allowed. 


" Block memory move functions, INT 15H, are not supported by the com- 
patability box, so block device drivers are out of the question. A program 
cannot issue the the INT 15H that switches the 80286 from real to 
protected mode. 


We have included this list of restrictions to inform you of the reasons why an 
existing DOS application might not run in the compatability box. There is no 
reason to write new compatability box applications for OS/2. The major decision 
application developers have to make is whether to create FAPI applications or full 
blown OS/2 applications. 


Family API Applications 


Family API applications can be run in OS/2’s protected mode, the compatabil- 
ity box (this is a non-choice), and in the PC-DOS 3.x environment on real mode- 
only machines. If such programs wish to run on 8086 machines they should not 
use 80286 instructions. The executable files for FAPI applications must fit within 
the DOS memory space, and have to restrict themselves to the memory available 
in the DOS address space. 

FAPI applications receive system services through a subset of the OS/2 API 
functions (see Appendix B for a complete listing of API functions as well as the 
FAPI subset). OS/2 API functions that are not included in the FAPI subset are 
those that are directly linked to the protected mode features of OS/2. Functions 
that perform the following tasks are excluded from the FAPI subset: 
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= Session Management Functions 

#" Device Monitor Functions 

= Interprocess Communications and Control Functions 
=" Advanced Timer Functions 

" Memory Management Functions above 640K 

# Asynchronous Execution Control Functions 


FAPI applications are created in the same manner as a regular OS/2 applica- 
tion. Once they are running in the OS/2 environment, they are passed through 
the BIND utility (see Chapter 9). This utility adds a DOS executable header to the 
OS/2 .EXE file, along with a stub loader routine which replaces all the API calls 
with their equivalent DOS and BIOS INT calls. For API calls that do not have DOS 
or BIOS equivalents the stub loader includes the actual code for these functions 
in the executable file. Because of this, FAPI .EXE files are typically larger than their 
protected mode-only counterparts. When an FAPI is executed in protected mode 
the DOS header, and stub loader are ignored and the program receives all system 
services through the API dynamic link libraries. 

FAPI applications can run both in real and protected mode, but do not receive 
the benefits of any of the protected mode features, except background multi- 
tasking and the use of the CALL API interface. It is possible for an application to 
determine the environment in which it is running (see Chapter 9 again), and thus 
to provide enhanced functionalities in protected mode, and to omit those 
functionalities in real mode. Pursuing such course, however, to any great length 
would seem to be a misuse of energy. If an application wishes to take advantage 
of OS/2 features in protected mode and still provide (reduced) support for real 
mode users, separate execution modules should be developed for both systems. 


Other Conversion issues 


As we have said, programs written in most high-level languages are relatively 
easy to port into the OS/2 environment. An OS/2 C compiler is already available, 
compilers for other high level languages (BASIC, Pascal, FORTRAN, and CO- 
BOL) are on the way. Converting 8088 assembly language programs for use in 
protected mode may be more difficult because of changes in program design 
philosophy. The issues involved in designing new applications to take specific 
advantage of OS/2 features (or redesigning old ones for that matter) are complex, 
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but different solutions will undoubtedly evolve as PC programmers become 
accustomed to a multiprograming environment. 

We have only one more tip for people who are porting applications into the 
OS/2 environment: Programs that formerly did video screen output by writing to 
the video screen one character ata time, repeatedly, might not perform adequately 
in protected mode. This is because OS/2 will interrupt the video I/O thread in 
between such calls in order to implement task switching. Programs which formerly 
wrote to the video screen one character at a time should write one line at a time. 











Appendix A 


_ 
OS/2 Commands and Utilities 





wo types of entities make up the OS/2 command environment: utilitiesand command 
interpreter internal functions. These commands and utilities are entered from the 
OS/2 or compatibility box command line. Utilities are implemented as executable 
files which reside on a disk and which must be loaded into memory when the utility is 
invoked. Command-interpreter internal functions, as the name implies, are part of the com- 
mand-interpreter .EXE file, and are memory resident. The system provides two command 
interpreters: CMD.EXE for protected mode and COMMAND.COM for the compatability box. 
Most of the commands and utilities supported by OS/2 have the same syntax as their real 
mode, PC-DOS counterparts, although their operation may be different. However there are 
several protected mode-only commands and utilities, and anumber of vestigial PC-DOS com- 
mands and utilities which have no meaning in protected mode, but which allow for the 
continued support of real mode and Family API applications. 
In this appendix we present a synopsis of each function’s purpose and syntax. For the 
experienced DOS user this will serve as a handy function use reference. Those who require 
additional information should consult an OS/2 command reference guide. 


[/O Redirection from the Command Line 


Justasitis possible fora parent process to redirectSTDIN andSTDOUT fora child process, 
itis also possible for the user to do so from the command line. One can redirect the STDIN 
and STDOUT for any OS/2 command, utility, or other program that writes to STDOUT and 
reads from STDIN. TheI/O redirection symbols for OS/2 are identical to those under PC- 
DOS, however, they are somewhat more useful in a multitasking environment. The follow- 
ing redirection symbols are recognized by OS/2: 


3 Changes STDIN. 

> Changes STDOUT. 

>> Appends STDOUT to the end ofa file. 

& Duplicates handle operator. Sends output meant for a numerically 


identifed I/O handle to another numerically identified handle. 
| Pipes output between programs, commands and utilities. 


These I/O operators can be used in avariety of situations. We will consider several examples. 


834 Advanced Programmer's Guide to OS/2 


With the “<“ operator, STDIN for a program or utility can be redirected to any valid file or 
input device. Using the “>” operator, STDOUT for a program utility may be changed. 

For example, when using the DETACH command to launch a program, it is possible to 
specify thata program is to sendand receive I/O to files instead of the video screen and keyboard. 
In this way, a program can be set torun in the background, but still receive input (from a data 
file containing the appropriate information), and indirectly do output. The format of this 
DETACH call is as follows: 


DETACH XLATE.EXE <XIN.DAT >XOUT.DAT 


The following example would take output from the CHKDSK command and append it 
onto the end ofthe file DISK.LOG. Each time the CHKDSKcommand is issued in this manner, 
its output is added to the end of the file DISK.LOG, keeping a record of the output of the 
CHKDSK utility. If the file pointed to by the “>>” operator does not exist, it is created. 


CHKDSK D: >>DISK.LOG 


The redirection facilities can also be used to redirect output by explicitly identifying a file 
handle (by its numerical identifier). ‘These handle redirection operators can be used with any 
of the STDIO file handles (from 0 to 9). In the simplest case, we can do something like this: 


FORMAT A: <FIN.DAT 1>FORMAT.OUT 2>&1 


Entering this from the command line has the following effect. First, the input for the 
FORMAT utility must be found in the file FIN.DAT. The next part of the command specifi- 
cation redirects all output sent toI/O handle 1 (STDOUT) to the file FORMAT.OUT. The 
last part of the command specification instructs OS/2 to merge the STDERR (I/O handle 2) 
output with the STDOUT output. In this case, both are sent to the file FORMAT.OUT. 

Inaslightly more complicated example, itis possible to send the output meant for several 
I/0 handles to only one (we are executing a program from the command line here): 


MYAPP 1>MYAPP.OUT 2>&1 3>&1 


This command has the effect of merging the output meant for STDOUT (I/O handle 2) 
and I/O handle 3 to STDOUT (J/O handle 1). STDOUT has itself been redirected to the 
file MYAPP.OUT. Only one redirection is allowed per handle. If one attempts to redirect an 
I/O handle to several different places, only the last redirection operation is recognized. The 
previous ones are ignored. 

The pipe operator (I) allows the STDOUT for a program or utility to be passed along to 
the STDIN of another program or utility. The data stream is redirected via an OS/2 system 
pipe. When two programs or utilities are executed while linked together by an OS/2 pipe 
operator, the programs or utilities are executed asynchronously. ‘The pipe operator is often 
used toimplement OS/2 filters (special OS/2 utilities which, much like device monitors, “filter” 
the data stream). For example: 


DIR | MORE 


sends the output from the directory command to the OS/2 MORE filter utility, which out- 
puts the DIR information to the video screen one screenload at a time. 
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In addition, the pipe utility can “chain” together two or more application programs. The 
STDOUT of one can be sent as the STDIN of the other. 


Common to DOS and OS/2 


Change Directory (CD) 

Syntax: CHDIR (CD) [drive:] path 

This function changes the current directory for the system. One may specify a full direc- 
tory path or just a directory name. If one specifies only a directory name, then it must be a 
child directory of the current one. If the command is invoked without any parameters, the 
current directory path is displayed. Ifthe command isinvoked with adrive letter, butno directory 
path, the current directory on the specified drive is displayed. 
Example: CD\OSATEXTS 

CD TXTS (this will only work from the directory OS/2) 


Change Drive 

Syntax: [driveletter]: 

Change the current default logical drive by simply entering the drive letter followed bya 
colon. 


Example: | d: (changes the current drive to d:) 
Change Code Page (CHCP) 
Syntax: CHCP codepage# 


This function changes the code page for the current session. It is equivalent to the Dos- 
SetPocCP function, except that itis invoked from the command line. One can only choose 
from the code pages previously defined with the CODEPAGE= command in the Config.sys 
file. If the command is invoked with no parameters, then the code page numbers for all the 
code pages loaded into the system are displayed. 

Example: Ifcode page 863 was defined in the Config.sys file, then one may switch to the Canadian 
code page in the following manner: 


CHCP 863 
Clear the Screen (CLS) 
Syntax: CLS 


This function clears the screen for the current session. It does not accept any parameters. 
Example: CLS 


Copy 

Syntax: COPY sourcespec targetspec 

The copy command copies files between drives, directories, and devices. Both the sourc- 
espec and the targetspec can include a fully qualified drive, path, and file name. In addition, 
both sourcespecand targetspeccan be specified as a device such as LPT 1 or CON. This allows for 
information to be typed directly from the keyboard into a file. File names can include the 
“wild-card” characters “*” and “>”. 
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Example: COPY CAWP\TEXTS\HERMESS A: (copies the file HERMES8 in the 
subdirectory C:\wp\texts to drive A:) 
COPY CON: OTXT.TXT (copies console input to the file QTXT.TXT 


in the current directory; console input is 
terminated with Ctrl-Z) 

COPY CAC\OBJ\*.LIB A: (copies every file with the extension .LIBin the 
directory C:\C\OBJ to drive A:) 


Set or Display the System Date (DATE) 

Syntax: DATE date 

One may display and set the system data with the DATE command. If the command is 
entered without parameters, then the current date appears on the screen, along with a prompt 
to change this date. A date parameter is expected in the following format: 

mm-dd-yy 

where mm is the month from 1-12 

where dd is the day from 1-31 

where vy is the year from 80-79 or 1980-2079 

The date information can be entered separated by “-”, “/”, or “.”. If the system is config- 
ured to supporta different national-language, then the order of the date information may be 
different. 
Example: DATE 12/25/89 (set the date to Christmas 1989) 


Display Contents of Directory (DIR) 

Syntax: DIR drive path filespecs /switches 

The DIR command outputs the contents of a specified directory onto the screen. The 
contents of a directory include a list of all subdirectories, filenames and extensions, the size 
(in bytes) of each file, and its creation date and time. Ifno parameters follow the DIR com- 
mand, then the contents of the current directory is output to the screen. As with all OS/2 
commands, the filespecsparameter can include “wild-cards.” Several useful switches are provided 
with this command: 


/P Pauses the output after a screenload of directory information has been out- 
put. Allows long directory listings to be read comfortably. 
/W Displays a directory listing in wide mode. This switch causes the directory 


command to print only the filenames and extensions omitting the rest of the 
directory information. 

Example: DIR CAQ\WEXE\*.LIB/p (displays all the files in the directory C\QEXE 
with the extension .LIB one screenful at a 
time) 

The DIR command can be used with the OS/2 PC-DOS I/O redirection facility, the pipe. 

For example, the command issued in the form: 


DIR C:\C\EXE\*.LIB|MORE 

has the same effect as the above example. Issuing the command in this form 
DIR A: |C:\DIRA.TXT 

sends a directory listing to the file named DIRA.TXT on drive C: 
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Delete a file 

Syntax: DEL drive path filespecs 

ERASE drive path filespecs 

Both the DELand ERASE commands delete afile or aspecified group of files from a specified 
drive and directory path. The file name specification can include “wild-cards” to erase groups 
of files. This command has no effect on files with read-only attributes. 
Example: DEL CATXT\*. BAK (deletes all the files with the extension .bak in 

the directory \IXT on drive C:) 


End the Command Interpreter (EXIT) 

Syntax: EXIT 

This command deletes nested copies of the command interpreter. However, it works a 
little bit differently in real and protected modes. In real mode, it only deletes additional copies 
of the command interpreter, but has no effect on the primary command interpreter. In 
protected mode, the EXIT command has the same effect, but if it is issued while the last (or 
primary) command interpreter for a session is in effect, the command causes the session to 
be terminated and returns control to the Session Manager. 
Example: EXIT 


Change the Disk Volume Label (LABEL) 

Syntax: LABEL drive volname 

This command changes a volume label fora hard drive or diskette. The volname parame- 
ter can be an ASCII string up to 11 characters long. Ifitis not included, then the command 
prompts the user for the volume label. Removable media such as diskettes should be labeled, 
since volume labels are always checked between diskette accesses. If diskettes have volume 
labels, then OS/2 will not write over anew disk when it has been inserted in the drive between 
disk accesses. This prevents data from being destroyed. 
Example: LABEL A: HERDISK 


Make a New Directory (MKDIR) 

Syntax: MD drive\path\dirname drive\path\dirname 

This command creates a subdirectory. In protected mode, it can be used to create mul- 
tiple subdirectories. Directory names can be up to eight characters long and can include a 
three-character extension. Ifonly the dirnameparameter is included, then the MD command 
creates a subdirectory with that name from the current directory. Asubdirectory name cannot 
duplicate the name of any other file or subdirectory name within the same directory. If this 
is attempted, the MD command fails. The new subdirectory name specification can include 
a full drive and path specification up to 63 characters in length. However, if a path name is 
specified, then every other directory in the path exceptfor the one(s) to be created must already 
exist. 


Example: MD OBJ (creates a subdirectory named OBJ in the 
current directory) 
MD OBJ SOURCE EXE (creates three subdirectories named OBJ, 


SOURCE, and EXE in the current directory— 
protected mode-only) 
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MD DATOOLS\MASM (appends the subdirectory MASM to the al- 
ready existing directory TOOLS on drive D:) 


Change the Command Line Prompt (PROMPT) 

Syntax: PROMPT prmptvar prmptvar etc. 

This command changes the default system prompt. It is followed by a series of parame- 
ters. Only the first parameter is separated from the command byaspace. The remainder are 
not separated by any spaces. The parameters can be strung together to create fairly complex 
system prompts. The possible values for prmptvarare: 


$a The “$” character 

$b The “|” character 

$C The “(” character 

$d The system date 

$e ASCII escape code: X‘1B’ 
$f The “)” character 

$g The “ >” character 

$n The default drive 


$p The current directory of the current drive 

$s A leading space 

$t The system time 

$$ The “$” character 

$- A carriage return and line feed 

Example: PROMPT $P$G (creates a system prompt having the form of 

the current drive and directory path followed 
bya” >”) 


Remove a directory (RMDIR) 

Syntax: RD drive\path\dirname drive\path\dirname 

This function removes a subdirectory. If the drive and path are not included, the func- 
tion removes a specified subdirectory from the current directory. In protected mode, sev- 
eral subdirectories may be deleted at once. 

A directory that contains files or subdirectories may not be deleted. In protected mode, 
a directory may not be deleted if it is the current directory for a process. 


Example: RD DATOOLS\MASM (deletes the subdirectory MASM from the 
directory TOOLS) 
RD MASM TXT (deletes the subdirectories MASM and TXT 


from the current directory) 


Rename a File (REN) 

Syntax: REN drive\path\oldname newname 

This command changes the name ofa file on a specified drive and path. Only the old file 
name (oldname) can have a drive and path specification. The newfile name (newname) simply 
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changes the name of the old file, but does not change its location on the disk. This function 

also accepts “wild-card” characters. 

Example: REN CAWPATXI\*.* *, DOC (renamesall the files in the specified directory 
to the files having the same name but the 
extension “.DOC”) 


Set an Environment Variable (SET) 

Syntax: SET varname=value 

The SET command assigns values to variables in the environment block. The variable 
name and value are separated by an equal sign (=) without any spaces. If the variable already 
exists, its value is updated. If the set command is issued without any parameters, it produces 
a listing of the values for the variables in the environment block. 
Example: SET PATH=CADOS;CAUTIL (sets a search path) 


Set or Display the System Time (TIME) 

Syntax: TIME time 

This command allows the system clock to be set. The time parameter takes the form 
hh:mm:ss.cc (h=hours, m=minutes, s=seconds, c=hundreths ofasecond). Normally the hours, 
minutes, and seconds are separated with colons (:), while the hundreths are separated from 
the seconds with a period (.), but this value is dependenton the country for which the machine 
is configured. The seconds and hundreths of a second values need not be specified. If not, 
these are automatically set to zero. If the command is issued without a parameter, then the 
current time is displayed, along with a prompt for the new time. 
Example: TIME 23:59 (set the system clock to one minute before 

midnight) 


Write-Verification Toggle (VERFY) 

Syntax: VERIFY toggle 

The VERIFY command either enables or disables verification for disk writing operations. 
Consequently the value of toggle can be either ON, or OFF. Enabling the disk-write verifica- 
tion ensures that important data is properly copied; however, the verification process slows 
down the writing process. It is not necessary for most purposes. 
Example: VERIFY ON (turn on disk-write verification) 


Display Volume Label (VOL) 


Syntax: VOL drivename drivename 
This command displays the volume label for a disk. In protected mode, several disks may 
be specified, separated by spaces. The volume label was either created when the media was 
formatted or through the LABEL command. 
Example: VOLA: (returns volume label for drive A:) 
VOL C: D: (returns volume labels for drives C: and D:, in 
protected mode) 
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Protected Mode Only 


Launch a Program in the Background (DETACH) 

Syntax: DET drive\path\progname parameters 

This command launches a detached or background program for a session from the 
command line. The command accepts a fully qualified file name and any parameters to be 
passed to that program from the command line. Acomplete discussion of the characteristics 
of detached programs is found in Chapter 2. 
Example: DET CAMON\KMON1.EXE 0 1 


Set the DPath environment variable (DPATH) 

Syntax: DAPTH path;[path J; 

This command sets the environment variable which defines the search path for DosOpen 
calls. Each path is separated by a semi-colon. This command overcomes a problem that is 
inherent to DOS: programs launched from a directory in which they do not reside cannot 
find external files (such as overlay files) when they call them. This is because DOS searches 
the current directory and not the one in which the overlay files reside. Under OS/2, one uses 
the DPATH command to launch programs which use overlay files from subdirectories other 
than their own. 

Example: DPATH CAE XE\VCACEXE\NEW;DASTAFRKFRED 


Start a New Session 

Syntax: START drive\path\progname parameter [parameter ]; 

This command allows a program to be launched from the OS/2 command line. Anew 
user selectable session is created for this program (the name of the program started in this 
manner appears on the Session Manager menu). The program launched via the start com- 
mand begins executing as a background session. The command line in the current session 
remains available. 

Example: START \OS2\CHKDSK C: (launches the Check Disk utility in a back- 
ground session. The user can immediately 
continue to input information at the com- 
mand line of the currentsession. The user can 
switch to the background session at any time 
to view the CHKDSK output.) 


Real Mode Only 


CTRL-BREAK Toggle 

Syntax: Break on/off 

This command enables or disables continual CTRL-BREAK checking under DOS 3.X. 
CTRL-BREAK is the user program termination signal under PC-DOS. If BREAK is on, then 
PC-DOS continuously monitors fora CTRL-BREAK. [fitis off, then it checks for CTRL-BREAK 
only when a program is receiving input from the keyboard. Under OS/2, the BREAK com- 
mand is meaningless, because CTRL-BREAK checking is always enabled. 
Example: BREAK ON 
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Utilities 
Common to DOS and 0S/2 


Displaying and Changing file attributes (ATTRIB) 

Syntax: ATTRIB drive\path\filespec [attribs ] /switch 

The ATTRIB utility displays or changes the attribute bits fora file ora group of files. Groups 
of files are indicated by wild-cards in the filespecparameter. Attribute bits are turned on and 
off by placing either a plus sign (on) or a minus sign (off) in front of the list of attribs. The 
following values for atiribare recognized: 


A Archive (Files with this bit set have been changed since the last backup) 

R Read-only (Files with this bit set cannot be modified) 

H Hidden File (Files with this attribute set do not appear in a normal directory 
listing) 


If the utility is invoked without the atiribs parameter list, then the utility returns the attrib- 
utes for the specified files. If (/S) isincluded then the utility also processes all subdirectories 
leading from the target directory. 

Example: ATTRIB\TXT\CH*.DOC +R +A (sets the attributes of all the specified files in 
the directory TXT to Archive and Read-Only) 


BACKUP 

Syntax: BACKUP sourcedrive\path\filespec targetdrive\path /switches 

This utility archives files. It can be set to archive all files on a specified drive or directory, 
or files individually. In addition, one can specify to archive only files created after a certain 
date, or only files that have been updated since the last backup (files whose Archive attribute 
bitis set). Any or several of the following switches may be included when using the BACKUP 
utility: 


/A Adds files that are being backed up to an already existing backup disk. This 
option only works in protected mode or for versions DOS 3.3 and later. 

/D Backs up files modified after a specified date. The date is specified in the format 
/D:mm-dd-yy, the same format that is acceptable to the DATE command. 

fF Formats the target disk if itis not already formatted. This does not work for 
hard drives. 

/L Creates a file where a log of the backed up files is placed. The full form of this 
switch is /L:drive\path\logfile. 

/M Updates only those files which have been changed since the last backup (those 
whose archive attribute bit is set). 

/S All subdirectories are also to be backed up. 

/T Backs up any file modified after a specified time. The full format for this switch 


is /T:hh:mmiss.cc, the same form acceptable to the TIME command. 


Example: BACKUP C\WORK\™.* A: /S/D:05-01-88 (backs up all the files in the directory 
\WORKorany ofits subdirectories 
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modified after April 1, 1988 onto 
drive A:) 


Checking the Disk Media (CHKDSK) 

Syntax: CHKDSK drive[\path\filespec] /switches 

This utility displays memory usage information for a specified disk. Any valid disk may be 
specified. Ifa path and file name specification appears (wild-cards are permitted), then OS/ 
2 also reports on how many different contiguous blocks of disk space a file occupies. 

The /f switch instructs CHKDSK to take steps to fix errors in the disk. The /voption allows 
you to watch the progress of the CHKDSK utility. 

When using the utility in protected mode, it cannot be used to repair the boot disk. This 
is because when fixing a disk, the CHKDSK utility must lock the drive. This prevents the OS/ 
2 kernel from accessing the boot disk, which it must constantly do, thus causing asystem crash. 
Example: CHKDSK D: 


Compare File Contents (COMP) 
Syntax: COMP drive\path\filespec drive\path\filespec 
The COMP utility compares the contents of two files or two sets of files. If the drive and 
path specification of the first file is specified, butnot the second, the utility assumes the second 
file resides in the same subdirectory. Of course, wild-card specifications can be used. 
Example: COMPATXT\*.DOC\BACK\ (comparesall the files with the extension .DOC 
in the \I'XT directory on drive C: with their 
counterparts in directory \BACK) 


DISKCOMP 

Syntax: DISKCOMP drive drive 

DISKCOMP compares two diskettes that have asimilarformat. The utility does notcompare 
dissimilarly formatted diskettes. 


Example: DISKCOMP A: A: (Compare two disks using the same drive) 
DISKCOPY 
Syntax: DISKCOPY sourcedrive targetdrive 


DISKCOPY makes an exact sector by sector copy of the source diskette to the target disk- 
ette. Ifthe target diskette is unformatted, DISKCOPYformats it. Ifthe same drive is specified 
as both source and target, DISKCOPY performs a single drive copy. 

Example: DISKCOPYA: B: (duplicates diskette in drive A: onto diskette 
in B:) 


(FIND) Filter 
Syntax: FIND = [/switches] “searchstring” drive\path\filespec 
[drive\pathfilespec] 

The FIND utility has two uses. It can filter (the term was introduced in first part of this 
section) records that do not contain a certain character string from the data stream, or it can 
be used to search for occurrences of a character string in an ASCII file. 

The selected string is specified by the parameter searchstring (which must be surrounded 
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by quotation marks). Ordinarily, FIND filters any records that do not contain this string from 
the data stream, or searches for occurrences of this string in an ASCII file(s). 

The swtches parameter specifies a list of switches that change the operation of the FIND 
utility. Several switches can be specified at once. Valid switches and their meanings are: 


/C Instructs FIND to return acount of the number of records matching the search 
string, rather than the actual records. 

/V Instructs FIND to select those records from the data stream which do not match 
the search string. This switch hasno meaning when searching ASCII files. 

/N Instructs FIND to display relative line numbers when searching an ASCII file. 


Its use is a little bit different in each case. Used asa filter, the STDOUT of another com- 
mand or utilility is piped into the STDIN for FIND using the OS/2 pipe facility. In this case, 
no fully qualified file name appears in the FIND statement; only the /switchesand “searchtext” 
parameters are used. 

Example: DIR A: | FIND /V “.BAK” (removes all files with the extension .BAK from 
the directory listing in drive A:) 

When using FIND to search fora string in an ASCII file, no wild-card characters can appear 
in the file specification. ‘his means that every file to be searched must be explicitly specified. 
Example: FIND “NORMA JEAN” cAcorresp\tr1.doc 


FORMAT 

Syntax: FORMAT drive /switches 

This utility prepares a hard disk or diskette for use with the OS/2/DOS file system. The 
/ switches parameter varies its operation. 


/4 Forces a high density (1.2MB) drive to format alow capacity (360K) diskette. 

JN, /1I These switches are used together when formatting 3 1/2 inch diskettes. /T 
specifies the number of tracks per side and /N specifies the number of sectors 
per track. The full format for each switch is as follows: /T:80 /N:8 (specifies a 
diskette with 80 tracks per side and 18 tracks per sector). 

/S Creates a bootable system diskette by transferring all the necessary system files 
to the formatted diskette. A target diskette must have at least 1.2 MB of storage 
capacity to create a bootable OS/2 diskette. In addition, all the files listed in 
the file FORMATS.TBL must reside in the root directory of the boot volume. 

/V Specifies a volume label while suppressing the FORMAT utilities’ prompt. This 
switch has the following format: /V:Vol_Label_Text. 


The OS/2 FORMAT command always prompts you for a volume label. OS/2 checks the 
volume label whenever it accesses a diskette to make sure it hasn’t been changed. The /V 
option is used to avoid the prompt. 

Example: FORMAT A:/s (creates a bootable diskette in drive A:) 


HELP 

Syntax: HELP msg# [off/on] 

This utility offers more information about any error message. Recall that OS/2 associates 
a unique number with each type of error and classifies them according to categories. If this 
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utility is used with the on/offoption, it enables or disables a help screen that appears above 
the command prompt in both protected mode and compatability box sessions. 
Example: HELP SYS802 (returns information on error 

message #802) 


MODE 


The MODE utility is quite powerful. It sets up the characteristics for a variety of devices. 
One can use the MODE utility to choose and configure the printer, and an asynchronous 
port and to choose the current video mode. 


Parallel Port Printer 


Syntax: MODE prni#, cpl, lpi, retry 
Where: 
prn# A valid parallel port printer PRN:, LPT1:, LPT 2:, etc. 
cpl The number of characters per line for that printer (80 or 132) 
lpr Lines per inch (6 or 8) 
retry Toggle which sets the infinite retry for the printer in case of printer time-outs. 
A value of “P” indicates that continual retry is enabled. 
Example: MODE LPT1: 80,8,P (sets LPT 1: to 80 chars per line, 8 lines per inch, 


with infinite retry) 


Asynchronous Port 


Syntax: MODE baud, parity, databits, Stopbits, TO=[val], XON=[val], 
IDSR=[val ], ODSR=[val ], OCTS=[val], DTR=[val], RTS=[val ] 

Where: 

baud Is one of the standard baud rates: 110, 150, 300, 600, 1200, 2400, 4800, 9600, 
19200. This parameter is required. Only the first two digits of the baud rate 
need to be specified. 

panty Specifies the parity. (E) ven, (O) dd, (N) one, (M)ark, and (S) pace are the possible 
values. If no parity is specified, OS/2 assumes Even. 

datalhits Specifies the number of data bits. Acceptable values are 5, 6, 7, or 8. Ifunspeci- 
fied, the default value is 7. 

stophits The stop bits may be 1, 1.5, or 2. For 110 baud the default is 2. Otherwise itis1. 


The following values are only allowed in protected mode: 


IQ= Infinite write time-out (ON or OFF). The default is OFF. 

XON= Automatic transmit flow control (ON or OFF). The default is OFF. 

IDSR= DSR, data-set-ready, input handshaking (ON or OFF). The default is ON. 
ODSR= DSR, data-set-ready, output handshaking (ON or OFF). The default is ON. 
OCTS= CTS, clear-to-send,DSR, output handshaking (ON or OFF). The defaultis ON. 
RTS= RTS, ready-to-send, control (ON, OFF, TOG, or HS). HS enables handshak- 


ing. TOG enables RTS toggling. The default value is ON. 
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Using the MODE utility in protected mode with only a COM port specification returns 
the current set up for that port. 
Example: MODE COM2: 96,N,8,1,RTS=HS (sets COM2: to 9600 baud, no parity, 8 data bits, 
1 stop bit, and RTS handshaking enabled) 


Video Mode 


Syntax: MODE vwiomode# 

This changes the video mode of the display for the session in which itis issued. The values 
and meanings for viomode# are as follows: 

CO col, row; where col specifies the number of character columns and row specifies 
the number of character rows. At this time, the only acceptable values for col are 80 and 40. 
For the MGA and CGA, the rows cannot be switched. For the EGA and VGA, row can be 43 
or 50. 
Example: MODE CO80,50 (sets the display to 80 columnswide, and 53 rows 
of text) 


(MORE) Filter 

Syntax: MORE 

MORE isan OS/2 filter which accepts data from the standard input data stream and sends 
it to the standard output device one screenful ata time. This utility is often used to view large 
files on screen without having information scroll out of view. 

Example: MORE < BIBLE.TXT (redirects the standard input data stream from 
the console to the file BIBLE.TXT. Then 
outputs it to the standard output device, the 
console, one screen ata time ) 

TYPE BIBLE.TXT | MORE (has the same effect, exceptis used in conjunc- 
tion with the type command and a pipe) 


Applying Software Patches (PATCH) 

Syntax: PATCH /switch drive\path\patchfile drive\path\filespec 

PATCH allows software patches to be applied to a program. Generally, itis used with the 
/ aswitch which updates programs from automatic patch file supplied by software vendors to 
upgrade software or fix bugs. In this case, one merely specifies the /aand the fully qualified 
name of the patch file, followed by the name of the file to be patched. The utility can also be 
run in manual mode where it prompts for an offset location within the file at which to start 
patching. It then displays the next 16 bytes in the file and allows the user to make changes. 
This utility should be used with caution since, improperly used, it can mangle files. 


Example: PATCH /A CHANGPRG.PAT MYAPP.EXE (applies patches from the file 
CHANGPRG.PAT 
to MYAPP.EXE) 

PRINT 


Syntax: PRINT drive\path\patchfile /switch [dev ] 
This utility either sends a file to the first available printer or allows you to choose the printer 
to which the file is to be sent. There are also switches that purge the print queue or cancel the 
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currently printing file. The PRINT utility sends output to the OS/2 print spooler. 


/D Selectsaprinter. (Can be any installed printer.) The switch is given in the form 
/D:DEVICE. 
/C Cancels the currently printing file. 
eT Cancels all the file in the print queue. 
Example: PRINT MYTEXT /D:LPT2 (sends the file MYTEXT to LPT2 *) 


Recreating Damaged Files and Directories (RECOVER) 

Syntax: RECOVER dir/path/[filespec] 

The RECOVER utility attempts to recover files that have developed bad sectors. It can be 
instructed to recover a directory, a file, ora group of files. Sadly, the information in the bad 
sectors is lost. OS/2 marks the bad sectors so as not to reuse them. 


Example: RECOVER C: (recovers root directory on drive C: ) 
RECOVER CATOOLS (recovers the file SERIOS.FIL in the 
\SERIOUS.FIL subdirectory \TOOLS on drive C:) 
REPLACE 
Syntax: REPLACE sourcedrive\path\filespec targetdrive\path /switches 


The REPLACE utility selectively replaces files in the target drive path specification. The 
utility matches up files in the target directory with the same names as those in the source file 
specification and replaces them. The /switches parameter changes the operation of the 
REPLACE utility. The recognized switches and their effects are as follows: 


/P Prompts one before a file is actually overwritten. It allows for even greater 
selectivity when replacing files. 
JR Overwrites those files marked read-only. 
JA Also copies files that match the source file specification, but do not existin the 
target directory 
/S Also replaces files in any subdirectories 
Example: Replace A\NEW\*.EXE C: /S (replaces any files with the specification *. EXE 


on every subdirectory on drive C: with the 
identical files on drive A:) 


(RESTORE) Backup 

Syntax: RESTORE sourcedrive targetdrive\path /switches 

The RESTORE utility brings back files previously restored with the BACKUP utility. One 
can restore files, groups of files, specified directories, or an entire disk. If the backed up files 
are spread across multiple diskettes, the REPLACE utility prompts you for a diskette change. 
If the directory structure has changed since the last backup (if the backed up subdirectories 
no longer exist), the RESTORE utility recreates them, as necessary. The following switches 
are supported by the RESTORE utility: 


/P Instructs RESTORE to prompt you before overwriting any files marked 
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read-only, or files changed since the last back up. 


/B Restores target files modified on or before a given date. The switch has the format 
/B:datewhere date is in the form acceptable by the DATE command. 

JA Restores target files modified on or after a given date. The switch has the 
format /A:datewhere date is in the form acceptable by the DATE command. 

FE Restores target files modified at or earlier than agiven time. The switch has the 
format /E:tzmewhere timeis in the form acceptable by the TIME command. 

/L Restores target files modified at or after a given time. The switch has the 
format /L:timewhere timeis in the form acceptable by the TIME command. 

/M Restores only those target files modified after the last back up. 

JN Only restores those files which no longer exist. 

Example: RESTORE A: CA /S /A:03-31-88 /P (restores all files on drive C: in all sub- 


directories modified after March 31, 1988; 
pauses for confirmation) 


(SORT) Filter 

Syntax: SORT /switches 

The SORT filter reads the data from STDIN and sends it to STDOUT in sorted form. 
Normally SORT sorts data in ascending alphabetical order, but it can also sort data in de- 
scending order. In addition itcan sorta file starting ata particular column. The action of the 
SORT filter is controlled by the / switches parameter: 


/R Sorts the data stream in reverse alphabetical order. 
/+# Where # is an integer representing a column number on which to begin 
sorting. 
Example: DIR B: |SORT /R (Display a directory listing in reverse order for 
drive A: ) 


Enable Print Spooler (SPOOL) 

Syntax: SPOOL \drive\spoolpath /D:[dev ] /O:[dev] 

The SPOOL utility starts the system spooler. The SPOOL utility takes print data sent by 
different processes and stores itin temporary files until it can be sent to an available printer. 
You can instruct the SPOOL utility to use a particular pre-existing directory for its temporary 
files. If you do not specify a subdirectory, it uses the SPOOL subdirectory on the current 
drive. The spooler is implemented using OS/2 device monitor facilities. 

The /D switch defines the device to be spooled. You can also instruct the spooler to send 
the output meant for the defined device to any other device that supports device monitors or 
a COM port using the /O switch. However, you cannot use the SPOOL utility to route data 
meant for one printer to another. 

In addition, starting the spooler from a command line in a session causes it to take over 
thatsession. Ifthisis not desired, then the spooler should be launched asa background process 
(using DETACH), or from the Config.sys file with the command RUN=SPOOL.EXE. 
Example: SPOOL DA\SPOODATA /D:LPT1 (starts the spooler, using the directory\SPOO- 

/O:COM1 DATA on drive D:; spooling all datameantfor 
LPT 1, and rerouting it to COM1) 
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Transfer Operating System (SYS) 

Syntax: SYS drivespec 

The SYS command copies the OS/2 hidden system files to an otherwise blank (but for- 
matted) disk. To create a bootable system disk it is also necessary to copy the CMD.EXE, 
COMMAND.COM, and all the files listed in the file FORMATS.TBL to the root directory of 
this diskette. OS/2 system disks must be 1.2 MB and 1.44 MB diskettes. 
Example: SYS A: (places the hidden system files on the diskette 

in drive A:) 


Display Directory Structure (TREE) 

Syntax: TREE drive /switch 

The TREE command displays the subdirectory structure for a disk. It accepts one switch, 
/¥, which displays the files contained in each subdirectory. 
Example: TREE C: 


Copy with Subdirectories (XCOPY) 

Syntax: XCOPY sourcedrive\path\filespec targetdrive\path\filespec /switches 

The XCOPY command is a supercharged version of the COPY command. With it, you 
can copy entire subdirectories, groups of files in a subdirectory, or even nested subdirecto- 
ries, and groups of files within them. Additionally, XCOPYduplicates the directory structure 
found on the source drive on the target drive. The XCOPYutility accepts the following switches 
which modify its operation: 


/S Also copies the specified contents of all the subdirectories leading from the 
source directory. Ifnecessary, it creates these subdirectories on the target drive. 
/E This switch may be used in conjunction with the /S switch. This switch copies 


the subdirectory structure from the source disk to the target disk, even if the 
directories on the source disk are empty. 


te Copies only those files whose archive bit is set. 

/M Copies only those files whose archive bit is set and resets the archive attribute 
for those files. 

/D Copies only those files modified on or after a specified date. The format for 
this switch is /D:date where the date parameter is in the form acceptable to 
the DATE command. 

Example: . XCOPYA:B:/S/E (copies every file from A: to B: including disk 


A.:’s subdirectory structure) 


Protected Mode Only 


Enable /Disable ANSI support (ANSI) 

Syntax: ANSI off/on 

The ANSI utility either enables or disables ANSI escape sequence processing for the VIO 
subsystem. Ifthe utility is invoked without parameters, then the current VIO state isreturned. 
This utility has no effect on the compatability box. The ANSI.SYS device driver must be installed 
to provide ANSI support for the compatability box. 
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Example: ANSI ON (enables ANSI support) 


Prepare a diskette to receive memory dump (CREATEDD) 

Syntax: CREATEDD drive 

This utility prepares a diskette to receive an OS/2 memory dump. If more than one disk- 
ette is required for the memory dump, only the first one must be prepared with the CREAT- 
EDD utility. 
Example: CREATEDD A: 


Manipulate Hard Disk Partitions (FDISK) 

Syntax: FDISK 

The FDISK utility manipulates partitions for hard drives. This utility is menu-driven, and 
fairly easy to use. It creates and deletes disk partitions and the logical drives associated with 
those partitions. It changes the current active partition and receives information on parti- 
tions and logical drives. If you add or delete a partition using this utility, the system reboots 
upon exiting this utility. 
Example: FDISK (invokes the FDISK utility; the first menu 

appears) 


Replace Primary Keyboard (KEYB) 

Syntax: KEYB country 

The KEYB utility switches the keyboard with one of those specified by the CODEPAGE= 
statement in the Config.sys file. The KEYB utility affects every session in the system including 
the compatability box. However the KEYB utility can only be invoked from a protected mode 
session. 

Hitting CTRL-ALT-F1 switches from the alternative keyboard back to the primary keyboard. 
Hitting CTRL-ALT-F2 switches back to the secondary keyboard. 

The following values for country are accepted by KEYB: 


BE Belgium NO Norway 

CF Canadian-French PO Portugal 

DK Denmark SP Spain 

FR France SV Sweden 

SU Finland SF Swiss-French 
GR Germany SG Swiss-German 
IT Italy UK British English 
US American English NL Netherlands 


LA Latin-American Spanish 


Enable/Disable Operating System Trace Logging (TRACE) 

Syntax: TRACE off/on tracets 

This utility enables or disables OS/2 logging of system traces. System traces are keptina 
buffer whose name is specified in the Config.sys file with the TRACEBUF statment. A log of 
system traces is simply a listing of all the API and system service functions OS/2 performs. If 
the TRACEBUF statement does not appear in the Config.sys file, then the TRACE utility has 
no effect. 
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Using the utility with either an ON or OFF specification enables system trace logging for 
all system traces. One can also selectively enable or disable traces by specifying a trace number(s) 
in addition to the ON or OFF parameter. There are 250 OS/2 trace codes. The major ones 
are as follows: 


10 Tasking services 

14 Program execution services 

18 IPC services 

1C Miscellaneous services 

24 Memory management services 
30 File system services 

38 Timer services 

60 Device management services 


61 IOCTL services 

62 DevHelp services 
64 KBD services 

6A. MOU services 

6C VIO services 

70-7F External interrupts 


80 Session Manager services 
83 Message retrieval services 
88 Queue services 
Example: TRACE ON 10,14,18 (turns on system trace logging for trace codes 


10, 14, and 18) 


Display System Trace Log (TRACEFMT) 
Syntax: TRACEFMT 
This utility formats the contents of the TRACE buffer for display purposes and sends it to 
STDOUT. Thisinformation can then be redirected to avariety of places. Recall thata TRACE 
buffer must have been allocated in the Config.sys file. If not, this utility generates an error. 
Example: TRACEFMT > TRACE3.88 (redirects the system trace data to the file 
TRACE3.88) 


Real Mode Only 


ASSIGN 
Syntax: ASSIGN newdrive=olddrive 
ASSIGN allows the compatability box to reroute data meant for one drive to another. 
Invoking this utility cancels any previous drive assignments. 
Example: ASSIGN C:=A: (sends and reads all data meant for/from drive 
A: to drive C:) 


Invoke DOS Line Editor (EDLIN) 
Syntax: EDLIN drive\path\filespec 
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EDLIN invokes the primitive line editor generally bundled with the DOS environment. 
The fully qualified name of the file to be edited is specified unless it resides in the current 


directory. 
Example: EDLIN CABAT\GO.BAT (invokes the line editor with the specified ASCII 
file) 
GRAFTABL 
Syntax: GRAFTABLE 


This utility loads a graphics mode character set for the ASCII characters 128-255. OS/2 
does not support graphics mode text for these characters in protected mode, so this utility 
only has an effect in the compatability box. 


Example: GRAFTABLE 
JOIN 
Syntax: JOIN joindrive todrive\dirname /switch 


The JOIN utility treats a logical drive as if it were a subdirectory on another logical drive. 
As far as the system is concerned, drive A: no longer exists. All I/O to that disk appears to be 
sent to the specified subdirectory. If the subdirectory does not exist on the specified drive, 
then JOIN creates it. A logical disk can only be joined to the root directory of another logical 
disk. Specifying the switch /D with the name of the joined drive cancels the JOIN operation. 
Invoking the utility with no parameters produces a listing of the currently joined drives. 


Example: JOIN A: CMDISK (this has the effect of treating drive A: as the 
subdirectory \ADISK on drive C:) 
JOIN A:/D (deletes the previous directory 
assignment) 


Unhide/Hide a COM Port (SETCOM40) 

Syntax: SETCOM40 Comport=on/off 

This utilityis not part of the standard DOS environment. Itisnecessary under OS/2, because 
of the problems involved in running compatability box applications along side protected mode 
applications. 

Normally, the OS/2 serial port driver instructs the BIOS to report to any DOS applica- 
tions that attempt to directly manipulate the COM hardware thatno COM ports are installed 
on the system. This prevents real mode applications from directly manipulating the COM 
port hardware. Thisis necessary because allowing compatability box applications to manipu- 
late the COM hardware in an unrestricted manner would interfere with protected mode 
applications writing toa COM port using the OS/2 serial port subsystem. Compatability box 
applications writing toa COM portusing DosOpen, DosRead, DosWrite, and DosClose functions 
continue to be allowed to use COM ports. 

However, if one is sure that no OS/2 protected mode applications will be using the COM 
ports, itis possible to “unhide” various COM ports to allow real mode applications to directly 
manipulate them. The initial SETCOM40 setting for all COM portsis OFF. Once areal mode 
program is finished manipulating a COM port(s), the SETCOM40 setting for that portshould 
be reset to OFF. 
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Example: SETCOM40 COM1=ON (unhides COM1 to allow for direct manipula- 
tion of the COM port hardware byareal mode 
application) 

SUBST 

Syntax: SUBST drive drive\dirname /switch 


SUBST allows a subdirectory to be treated as a virtual disk drive. Ifany programs read or 
write to the specified drive letter, the data actual comes from or goes to the specified direc- 
tory. Invoking the utility with no parameters producesa listing ofall the current virtual drives. 
Invoking the utility with a drive letter and the /D switch deletes a virtual drive. 

Example: SUBST J: CAXTRA (treats the subdirectory CAXTRA like drive J:) 














Tasking Functions 


Function Name 


DosCreateThread 
DosCwait 
DosEnterCritSec 
DosExecPgm 
DosExit 
DosExitList 
DosGetPid 
DosGetPrty 
DosKillProcess 
DosMonClose 
DosMonOpen 
DosMonRead 
DosMonReg 
DosMonWrite 
DosPTrace 
DosResumeThread 
DosSelectSession 
DosSetPrty 
DosSetSession 
DosSleep 
DosStartSession 
DosStopSession 
DosSuspendThread 
DosSystemService 
DosTimerAsync 
DosTimerStart 
DosTimerStop 


Appendix B 





API Functions 


Description INT 21H 
Create a thread 

Wait on child process termination 4DH 
Enter critical section 

Execute program 4BH 

Exit program 00H, 4CH 


Register list of exit routines 

Get process ID # 

Get process priority level 
Terminate process 

Remove device monitor 

Enable device monitor 

Monitor read from data stream 
Register monitor buffers 
Monitor write to monitor helper 
Process debugging interface 
Restart thread 

Place a session into the foreground 
Set a process’ priority 

Set session status 

Temporarily disable process execution 
Launch a session 

Stop a session 

Suspend thread execution 
Request special process services 
Start asynchronous timer 

Start count-down timer 

Stop timer 


Interprocess Communication (IPC) Functions 


Function Name 


DosCloseQueue 
DosCloseSem 
DosCreateQueue 
DosCreateSem 
DosFlagProcess 
DosHoldSignal 
DosMakePipe 
DosMuxSemWait 


DosOpenQueue 


Description 


Close a queue 

Close system semaphore 

Create a queue 

Create a system semaphore 

Set the external event flag for a process 
Enable or disable signal handling 

Create a pipe 

Level-triggered semaphore function: wait 
on one of many semaphores 

Gain access to a queue 


FAPI 


No 
Limited 
No 
Yes 
Limited 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 


FAPI 


No 
No 
No 
No 
No 
Limited 
No 
No 


No 
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DosOpenSem 
DosPeekQueue 
DosPurgeQueue 
DosQueryQueue 
DosReadQueue 
DosSemClear 
DosSemRequest 
DosSemSet 
DosSemSetWait 
DosSemWait 
DosSendSignal 
DosSetSigHandler 
DosWriteQueue 


Gain access to a semaphore 
Examine an element on queue 
Empty queue of contents 
Query size of queue 

Read element from queue 
Clear semaphore 

Obtain access to semaphore 
Set a semaphore 

Set semaphore and wait until it clears 
Wait for semaphore to clear 
Send a signal 

Set up signal handlers 

Write to a queue 


Memory Management Functions 


Function Name 


DosAllocHuge 
DosAllocSeg 
DosAllocShrSeg 
DosCreateCSAlias 


DosFreeSeg 
DosGetHugeShift 
DosGetInfoSeg 
DosGetSeg 
DosGetShrSeg 
DosGiveSeg 
DosLockSeg 
DosMemAvail 
DosReallocHuge 
DosReallocSeg 
DosSubAlloc 
DosSubFree 
DosSubSet 
DosUnlockSeg 


File |/O Functions 


Function Name 


DosBufReset 
DosChDir 
DosChgFilePtr 
DosCLIAccess 
DosClose 
DosDelete 
DosDevConfig 
DosDevIOCTL 
DosDupHandle 
DosFileLock 
DosFindClose 
DosFindFirst 
DosFindNext 
DosGetMessage 
DosInsMessage 
DosMkDir 
DosMove 
DosNewSize 
DosOpen 
DosPhysicalDisk 
DosPortAccess 


Description INT 21H 
Allocate a huge memory block 
Allocate memory segment 48H 


Allocate a shared segment 

Creates an aliased executable segment 

for a data segment 

Free memory segment 49H 
Get shift parameter for huge block 

Get selector for system info segment 

Get access to segment 

Get access to shared segment No 
Grant access to segment 

Lock segment in memory 

Return size of largest free memory block 

Change size of huge block 

Change size of segment 4AH 
Sub-allocate memory block 

Free sub-allocated memory block 

Set memory sub-allocation size 

Unlock segment 


Description INT 21H 
Write file cache to disk QDH, 68H 
Change directory 3BH 
Change position of file pointer 42H 
Request disable interrupt handling 

Close file 3EH 
Delete file 41H 

Get device configuration 

Make IOCTL call 44H 
Duplicate file handle 45H, 46H 
Lock (section) of file 5CH 
Close directory handle 

Find first matching file 4EH 

Find next matching file 4FH 


Retrieve message from message file 
Insert variable information in message 


Create a directory 39H 

Move a file 56H 
Change file size 

Open a file 3CH, 3DH 


Request partition info 
Request I/O port access 


No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
No 
Limited 
No 


FAPI 


Limited 
Limited 
No 
Yes 


Yes 
Yes 
No 
No 


No 
No 
No 
Limited 
Limited 
Yes 
Yes 
Yes 
No 


FAPI 


No 
Yes 
Yes 
Yes 
Yes 
Yes 
Yes 
Yes 
Yes 
Limited 
Limited 
Limited 
Limited 
Yes 
Yes 
Yes 
Yes 
Yes 
Limited 
No 
Yes 





























DosPutMessage 
DosQCurDir 
DosQCurDisk 
DosQFHandState 
DosQFileInfo 
DosQFileMode 
DosQFSInfo 
DosQHandInfo 
DosQVerify 
DosRead 
DosReadAsynch 
DosRmDir 
DosSearchPath 
DosSelectDisk 
DosSetFHandState 
DosSetFileInfo 
DosSetFileMode 
DosSetFSInfo 
DosSetMaxFH 
DosSetVerify 
DosWrite 
DosWriteAsynch 


Output message to file handle 
Query current directory 
Query current drive 
Query file handle state 
Query file information 
Query file mode 

Query file system info 
Query file handle type 
Query write verify setting 
Read file 

Read file asynchronously 
Remove directory 

Search path for file 

Select default disk 

Set file handle state 

Set file information 

Set file mode 

Set file system info 

Set maximum file handles 
Enable or disable write verification 
Write file 

Write file asynchronously 


Video (VIO) Functions 


Function Name 


VioDeRegister 
VioEndPopUp 
VioGetANSI 
VioGetBuf 
VioGetConfig 
VioGetCP 
VioGetCurPos 
VioGetCurType 
VioGetFont 
VioGetMode 
VioGetPhysBuf 
VioGetStae 
VioNodeUndo 
VioPopUp 
VioPrtSc 
VioPrtScToggle 
VioReadCellStr 
VioReadCharStr 
VioRegister 
VioSaveRedrawUndo 
VioSaveRedrawWait 
VioScrLock 
VioScrollDn 
VioScrollLf 
VioScrollRt 
VioScrollUp 
VioScrUnlock 
VioSetANSI 
VioSetCP 
VioSetCurPos 
VioSetCurType 
VioSetFont 
VioSetMOde 
VioSetState 
VioShowBuf 
VioWrtCellStr 


Description 


Deregister replacement video subsystem 
End background popup 
Get ANSI status 

Get logical video buffer 
Get video configuration 
Get video code page ID 
Get cursor position 

Get cursor type 

Get font table address 

Get display mode 

Get physical display buffer 
Get video state 

Cancel mode wait 

Begin background pop-up 
Print screen 
Enable/disable VioPrtSc 
Read cell string 

Read character string 
Register replacement video subsystem 
Cancel save—redraw 

Wait and save—redraw 
Lock the screen 

Scroll down 

Scroll left 

Scroll right 

Scroll up 

Unlock screen 
Enable/disable ANSI mode 
Set code page ID 

Set cursor position 

Set cursor type 

Set video character font 
Set display mode 

Set Video State 

Display logical buffer 
Write cell string 


API Functions 


47H 
19H 


57H 
43H 
36H 


54H 
3FH 


3AH 
OEH 


57H 
43H 


67H 
ral gl 
40H 


INT 10H 


03H 


OFH 


08H 


07H 


06H 


02H 
01H 


00H 
OBH 


09H 


855 


Yes 
Yes 
Yes 
Limited 
Yes 
Yes 
Yes 
No 
Yes 
Yes 
No 
Yes 
Yes 
Yes 
Limited 
Yes 
Yes 
Yes 
Yes 
Yes 
Yes 
No 


FAPI 


No 
No 
No 
Yes 
No 
No 


Yes 
Nos 
Yes 
Yes 
No 
No 
No 
No 
No 
Yes 
Yes 


Yes 


Yes 
Yes 
No 
Yes 
No 
Yes 
Yes 


856 Advanced Programmer's Guide to OS/2 


VioWrtCharStr 
VioWrtCharStrAttr 
VioWrtNAttr 
VioWrtNCell 
VioWrtNChar 
VioWrtTTY 


Write character string 

Write character string with attribute 
Write N attributes 

Write N cells 

Write N characters 

Write a TTY string 


Keyboard (KBD) Functions 


Function Name 


KbdCharIn 
KbdClose 
KbdDeRegister 
KbdFreeFocus 
KbdFlushBuffer 
KbdGetFocus 
KbdGetStatus 
KbdGetCP 
KbdOpen 
KbdPeek 
KbdRegister 
KbdSetCp 
KbdSetCustXT 
KbdSetFgnd 
KbdSetStatus 
KbdShellInit 
KbdStringIn 
KbdSynch 
KbdXlate 


Description 


Read character and scan code 
Close logical keyboard 


Deregister replacement keyboard subsystem 


Free keyboard focus 

Flush keyboard buffer 

Get keyboard focus 

Get keyboard staus 

Get Kbd code page ID 

Open logical keyboard 
Examine character and scan code 
Register replacement subsystem 
Set code page ID 

Set custom translate table 

Set foreground kbd priority 

Set keyboard status 

Initialize shell 

Read character string 
Synchronize kbd access 
Translate scan code 


Mouse (MOU) Functions 


Mouse API functions cannot be used by FAPI applications. The DOS 33H instructions included in the listing are 


approximately equivalent to the OS/2 API functions. 


Function Name 


MouClose 
MouDeRegister 
MouDrawPtr 
MouFlushQue 
MouGetDevStatus 
MouGetEventMask 
MouGetHotKey 
MouGetNumButtons 
MouGetNumMickeys 
MouGetNumQueE] 
MouGetPtrPos 
MouGetPtrShape 
MouGetScalefact 
MoulnitReal 
MouOpen 
MouReadEventQueue 
MouRegister 
MouRemovePtr 
MouSetDevStatus 
MouSetEventMask 
MouSetHotKey 
MouSetPtrPos 
MouSetPtrShape 
MouSetScaleFact 
MouShelllInit 
MouSych 


Description 


Close mouse device 

Deregister a replacement subsystem 
Draw a mouse pointer 

Flush mouse event queue 

Get mouse device status flags 

Get mouse event mask 

Get mouse hot-key definition 

Get number of mouse buttons 

Get # of mickeys/centimeters 

Get # of elements on event queue 
Get mouse pointer position 

Get mouse pointer shape 

Get mouse scaling factor 

Initialize real mode mouse device driver 
Open mouse device 

Read mouse event queue 

Register replacement subsystem 
Remove mouse pointer from screen area 
Set mouse status flags 

Set mouse event mask 

Set mouse hot-key definition 

Set mouse pointer position 

Define mouse pointer shape 

Set mouse scaling factor 

Intialize shell linkage 

Synchronize mouse subsystem 


OAH 


OEH 


DOS Equivalent 
INT 16H,00H 


INT 16H, 00H 


INT 16H, 00H 


INT 21H, 0AH 


Yes 
Yes 
Yes 
Yes 
Yes 
Yes 


FAPI 


Yes 
No 
No 
No 
Yes 
No 
Yes 
No 
No 
Limited 
No 
No 
No 
No 
No 
No 
Yes 
No 
No 


only 


INT 33H 


O1H 


03H 


00H 
05H,06H 


02H 
0CH 


04H 
09H, 0AH 

















Miscellaneous Functions 


Function Name 


BadDynLink 
DosBeep 
DosCaseMap 
DosErrClass 
DosError 
DosFreeModule 
DosGetCollate 
DosGetCP 
DosGetCtryInfo 
DosGetDateTime 
DosGetDBCSEv 
DosGetEnv 
DosGetMachineMode 
DosGetMessage 
DosGetModHandle 
DosGetModName 
DosGetProcAddr 
DosGetVersion 
DosInsMessage 
DosLoadModule 
DosPutMessage 
DosScanEnv 
DosSetCp 
DosSetDateTime 
DosSetVet 


Description 


Routine called upon bad dynamic link 


Beep 
Case character string 
Classify error code 


Enable hard error processing 
Free dynamic link module 
Get collating sequence table 
Get process code page ID 
Get foreign country info 

Get system date and time 


Get dual byte char set 


Get environment string address 


Get processor mode 
Retrieve message 


Get dynamic link module handle 

Get dynamic link module name 

Get dynamic link procedure address 

Get OS version number 

Insert variable text into retrieved message 
Load dynamic link module 

Writes message to device handle 

Scan environment strings 


Set process code page 


Set system date and time 
Specify exception handling routine 


API Functions 


INT 21H 


59H 


66H 
38H 
2AH, 2CH 
65H 


30H 


66H 
2BH, 2DH 
25H 
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FAPI 


Yes 
Yes 
Yes 
Limited 
Limited 
No 
Yes 
No 
Limited 
Yes 
No 
Yes 
Yes 
Yes 
No 
No 
No 
Yes 
Yes 
No 
Yes 
Yes 
No 
Yes 
Yes 
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OS /2 Error Codes 


DOS 2.0 error codes: 


NO_ERROR 0 
ERROR_INVALID_ FUNCTION 1 
ERROR_FILE_NOT_FOUND 2 
ERROR_PATH_NOT_FOUND 5 
ERROR_TOO_MANY_OPEN_FILES 4 
ERROR_ACCESS_DENIED 5 
ERROR_INVALID_HANDLE 6 
ERROR_ARENA_ TRASHED 7 
ERROR_NOT_ENOUGH_MEMORY 8 
ERROR_INVALID_BLOCK 9 
ERROR_BAD_ENVIRONMENT 10 
ERROR_BAD_ FORMAT 11 
ERROR_INVALID_ ACCESS 12 
ERROR_INVALID_DATA 13 
*EREEK reserved 14 
ERROR_INVALID_DRIVE 15 
ERROR _CURRENT_DIRECTORY 16 
ERROR_NOT_SAME_DEVICE vi 
ERROR_NO_MORE_FILES 18 
OS/2 Mappings for INT 24 Errors 
ERROR_WRITE_PROTECT 19 
ERROR_BAD_UNIT 20 
ERROR_NOT_READY yl 
ERROR_BAD_COMMAND Ze 
ERROR_CRC 23 
ERROR_BAD_LENGTH 24 
ERROR_SEEK 25 
ERROR_NOT_DOS_DISK 26 
ERROR_SECTOR_NOT_FOUND ya 
ERROR_OUT_OF_ PAPER 28 
ERROR_WRITE_FAULT 29 
ERROR_READ_ FAULT 30 
ERROR_GEN_FAILURE 3] 


DOS 3.0 Error codes reported through INT 24 


ERROR_SHARING_VIOLATION 52 
ERROR_LOCK_VIOLATION 33 
ERROR_WRONG_DISK 34 
ERROR_FCB_UNAVAILABLE 20 


ERROR_SHARING_BUFFER_EXCEEDED 36 














ERROR_NOT_SUPPORTED 
ERROR_NETWORK_ACCESS_ DENIED 


DOS 3.0 Errors 


ERROR_FILE_EXISTS 
ERROR_DUP_FCB 
ERROR_CANNOT_MAKE 
ERROR_FAIL_I24 


DOS 3.0 Network Related Errors 


ERROR_OUT_OF_STRUCTURES 
ERROR_ALREADY_ASSIGNED 
ERROR_INVALID_PASSWORD 
ERROR_INVALID_PARAMETER 
ERROR_NET_WRITE_FAULT 


0S/2 Specific Errors 


ERROR_NO_PROC_SLOTS 
ERROR_NOT_FROZEN 

ERR_TSTOVFL 

ERR_TSTDUP 

ERROR_NO_ITEMS 

ERROR_INTERRUPT 
ERROR_TOO_MANY SEMAPHORES 
ERROR_EXCL_SEM ALREADY OWNED 
ERROR_SEM_IS SET 
ERROR_TOO_MANY_SEM_REQUESTS 
ERROR_INVALID_AT_INTERRUPT_TIME 
ERROR_SEM_ OWNER DIED 
ERROR_SEM_USER_LIMIT 
ERROR_DISK_CHANGE 
ERROR_DRIVE_LOCKED 
ERROR_BROKEN_PIPE 
ERROR_OPEN_FAILED 
ERROR_BUFFER_OVERFLOW 


ERROR_DISK_FULL 
ERROR_NO_MORE_SEARCH_HANDLES 


ERROR_INVALID_TARGET_HANDLE 
ERROR_PROTECTION_VIOLATION 
ERROR_VIOKBD_REQUEST 
ERROR_INVALID_CATEGORY 
ERROR_INVALID_VERIFY_SWITCH 
ERROR_BAD_DRIVER_LEVEL 
ERROR_CALL_NOT_IMPLEMENTED 
ERROR_SEM_TIMEOUT 
ERROR_INSUFFICIENT_BUFFER 
ERROR_INVALID_NAME 
ERROR_INVALID_LEVEL 
ERROR_NO_VOLUME_LABEL 


ERROR_MOD_NOT_FOUND 
ERROR_PROC_NOT_FOUND 


ERROR_WAIT_NO_CHILDREN 
ERROR_CHILD_NOT_COMPLETE 
ERROR_DIRECT_ACCESS_ HANDLE 


ERROR_NEGATIVE_SEEK 
ERROR_SEEK_ON_DEVICE 
ERROR_IS_JOIN_TARGET 


E14 
115 
116 
117 
118 
119 
120 
L21 
122 
123 
124 
125 


126 
127 


128 
129 
130 


131 
132 
1338 


OS/2 Error Codes 859 


No process slots available. 


Timer service table overflow 

Timer service table duplicate 

There were no items to operate upon 
Interrupted system call 


Waitsem found owner died 

Too many processes on semaphore 

Insert disk B: into drive A: 

Drive locked by another process 

Write to pipe with no reader 

Open/create failed due to explicit fail command 
Buffer passed to system call is too small to hold 
return data 

Not enough space on the disk 

Can’t allocate another search structure or handle 
(DOSFINDFIRST) 

Target handle in DOSDUPHANDLE is invalid 
Bad user virtual address 


Category for DEVIOCTL is not defined 

Invalid value passed for verify flag 

No level four device driver for DEVIOCTL 
Returned by FAPI calls with no patches 
Semaphore timeout 

Buffer passed to AP] function too small 

Illegal character or malformed file system name 
Unimplemented level for info retrieval or setting 
No volume label found with DosQFSInfo 
command 

No module found by run-time dynamic link call 
No procedure address found by run-time dynamic 
link call 

DosCWait finds no children 

DosCWait children not complete 

Handle operation is invalid for direct disk access 
handles 

Negative offset specified 

Application tried to seek on device or pipe 
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ERROR_IS_JOINED 134 
ERROR_IS_SUBSTED 135 
ERROR_NOT_JOINED 136 
ERROR_NOT_SUBSTED 137 
ERROR_JOIN_TO_JOIN 138 
ERROR_SUBST_TO_SUBST 139 
ERROR_JOIN_TO_SUBST 140 
ERROR_SUBST_TO_JOIN 141 
ERROR_BUSY_DRIVR 142 
ERROR_SAME_DRIVE 143 
ERROR_DIR_NOT_ROOT 144 
ERROR_DIR_NOT_EMPTY 145 
ERROR_IS_SUBST_PATH 146 
ERROR_IS_JOIN_PATH 147 
ERROR_PATH_ BUSY 148 
ERROR_IS_ SUBST_TARGET 149 
ERROR_SYSTEM_TRACE 150 
ERROR_INVALID_EVENT_COUNT 151 
ERROR_TOO_MANY_MUXWAITERS 152 
ERROR_INVALID_LIST_FORMAT 153 
ERROR_LABEL_TOO_LONG 154 
ERROR_TOO_MANY_TCBS 155 
ERROR_SIGNAL_REFUSED 156 
ERROR_DISCARDED 157 
ERROR_NOT_LOCKED 158 
ERROR_BAD_THREADID_ADDR 159 
ERROR_BAD_ARGUMENTS 160 
ERROR_BAD_PATHNAME 161 
ERROR_SIGNAL_PENDING 162 
ERROR_UNCERTAIN_ MEDIA 163 
ERROR_MAX THRDS REACHED 164 
ERROR_MONITORS_NOT_SUPPORTED 165 
ERROR_INVALID_SEGMENT_NUMBER 180 
ERROR_INVALID_CALLGATE 18] 
ERROR_INVALID_ORDINAL 182 
ERROR_ALREADY EXISTS 183 
ERROR_NO_CHILD_ PROCESS 184 
ERROR_CHILD_ALIVE_NOWAIT 185 
ERROR_INVALID_FLAG_NUMBER 186 
ERROR_SEM_NOT_FOUND 187 


Loader Errors: 


ERROR_INVALID_STARTING_CODESEG 188 
ERROR_INVALID_STACKSEG 189 
ERROR_INVALID_MODULETYPE 190 
ERROR_INVALID_EXE_SIGNATURE 19] 
ERROR_EXE_MARKED_INVALID 192 
ERROR_BAD_EXE_FORMAT 193 
ERROR_ITERATED_DATA_EXCEEDS_64k 194 
ERROR_INVALID_MINALLOCSIZE J95 
ERROR_DYNLINK_FROM_INVALID_RING 196 
ERROR_IOPL_NOT_ENABLED 197 
ERROR_INVALID_SEGDPL 198 
ERROR_AUTODATASEG_EXCEEDS_64k 199 
ERROR_RING2SEG_MUST_BE_MOVABLE 200 
ERROR_RELOC_CHAIN_XEEDS_SEGLIM 201 
ERROR_INFLOOP_IN_RELOC_CHAIN 202 
ERROR_ENVVAR_NOT_FOUND 203 
ERROR_NOT_CURRENT_CTRY 204 
ERROR_NO_SIGNAL_SENT 205 
ERROR_FILENAME_EXCED_RANGE 206 if filename > 83 for FAPI if “*a” > 83 
ERROR_RING2_STACK_IN_USE 207 
ERROR_META_EXPANSION_TOO_LONG 208 
ERROR_INVALID_SIGNAL_NUMBER 209 


ERROR_THREAD_1]_INACTIVE 210 











ERROR_INFO_NOT_AVAIL 
ERROR_LOCKED 
ERROR_BAD_DYNALINK 
ERROR_TOO_MANY_ MODULES 
ERROR_NESTING_NOT_ALLOWED 


ERROR codes 230 - 249 are reserved 


ERROR_INVALID_PROCID 
ERROR_INVALID_PDELTA 
ERROR_NOT_DESCENDANT 
ERROR_NOT_SESSION_MANAGER 
ERROR_INVALID_PCLASS 
ERROR_INVALID_SCOPE 
ERROR_INVALID_THREADID 
ERROR_DOSSUB_SHRINK 
ERROR_DOSSUB_NOMEM 
ERROR_DOSSUB_OVERLAP 
ERROR_DOSSUB_BADSIZE 
ERROR_DOSSUB_BADFLAG 
ERROR_DOSSUB_BADSELECTOR 
ERROR_MR_MSG_TOO_LONG 
ERROR_MR_MID_NOT_FOUND 
ERROR_MR_UN_ACC_MSGF 
ERROR_MR_INV_MSGF_FORMAT 
ERROR_MR_INV_IVCOUNT 
ERROR_MR_UN_PERFORM 
ERROR_TS_WAKEUP 
ERROR_TS_SEMHANDLE 
ERROR_TS_NOTIMER 
ERROR_TS_HANDLE 
ERROR_TS_DATETIME 
ERROR_SYS_INTERNAL 
ERROR_QUE_CURRENT_NAME 
ERROR_QUE_PROC_NOT_OWNED 
ERROR_QUE_PROC_OWNED 
ERROR_QUE_DUPLICATE 
ERROR_QUE_ELEMENT_NOT_EXIST 
ERROR_QUE_NO_MEMORY 
ERROR_QUE_INVALID_NAME 
ERROR_QUE_INVALID_PRIORITY 
ERROR_QUE_INVALID_HANDLE 
ERROR_QUE_LINK_NOT_FOUND 
ERROR_QUE_MEMORY_ERROR 
ERROR_QUE_PREV_AT_END 
ERROR_QUE_PROC_NO_ACCESS 
ERROR_QUE_EMPTY 
ERROR_QUE_NAME_NOT_EXIST 
ERROR_QUE_NOT_INITIALIZED 
ERROR_QUE_UNABLE_TO_ACCESS 
ERROR_QUE_UNABLE_TO_ADD 
ERROR_QUE_UNABLE_TO_INIT 
ERROR_VIO_INVALID_MASK 
ERROR_VIO_PTR 
ERROR_VIO_MODE 
ERROR_VIO_WIDTH 
ERROR_VIO_ROW 
ERROR_VIO_COL 
ERROR_VIO_WAIT_FLAG 
ERROR_VIO_UNLOCK 
ERROR_SGS_NOT_SESSION_MGR 
ERROR_SMG_INVALID_SESSION_ID 
ERROR_SMG_NO_SESSIONS 
ERROR_SMG_SESSION_NOT_FOUND 
ERROR_SMG_SET_TITLE 
ERROR_KBD_PARAMETER 
ERROR_KBD_INVALID_IOWAIT 


yA 
212 
213 
214 
215 


OS/2 Error Codes 861 


Invalid process id 

Invalid priority delta 

Not descendant 

Requestor not session manager 
Invalid p class 

Invalid scope 

Invalid thread id 

Can’t shrink - MspSet 

No memory - MspAlloc 

Overlap - MspFree 

Bad size parameter - MspAlloc or MspFree 
Bad flag parameter - MspSet 

Invalid MspSegment Selector 
Message too long for buffer 

Message id number not found 
Unable to access message file 

Invalid message file format 

Invalid insertion variable count 
Unable to perform function 

Unable to wake up 

User passed invalid system semaphore 
No timer available 

Invalid timer handle 

Date or time invalid 

Internal system error 

Current name does not exist 
Current process does not own queue 
Current process owns queue 
Duplicate name 

Element does not exist 

Inadequate memory 

Invalid name 

Invalid priority parameter 

Invalid queue handle 

Link not found 

Memory error 

Previous element was at end of queue 
Process does not have access to queue 
Queue is empty 

Queue name does not exist 

Queues not initialized 

Unable to access queue 

Unable to add new queue 

Unable to initialize queues 

Invalid replacement mask 

Invalid pointer to parameter 
Unsupported screen mode 

Invalid cursor width value 

Invalid row value 

Invalid column value 

Invalid wait flag setting 

Screen not previously locked 

Caller not session manager 

Invalid session id 

No sessions available 

Session not found 

Title set by shell or parent can’t be changed 
Invalid parameter to kbd 

Invalid I/O wait specified 


862 


ERROR_KBD_INVALID_LENGTH 
ERROR_KBD_INVALID_ECHO_MASK 
ERROR_KBD_INVALID_INPUT_MASK 
ERROR_MON_INVALID_PARMS 
ERROR_MON_INVALID_DEVNAME 
ERROR_MON_INVALID_HANDLE 
ERROR_MON_BUFFER_TOO_SMALL 
ERROR_MON_BUFFER_EMPTY 
ERROR_MON_DATA_TOO_LARGE 
ERROR_MOUSE_NO_DEVICE 
ERROR_INVALID_FREQUENCY 
ERROR_NLS_NO_COUNTRY FILE 
ERROR_NLS_OPEN_FAILED 
ERROR_NLS NO _CTRY CODE 
ERROR_NO_COUNTRY_OR_CODEPAGE 
ERROR_NLS_TABLE_TRUNCATED 
ERROR_NLS_BAD_TYPE 
ERROR_NLS_TYPE_NOT_FOUND 
ERROR_VIO_SMG_ ONLY 
ERROR_VIO_INVALID_ASCIIZ 
ERROR_VIO_DEREGISTER 
ERROR_VIO_NO_POPUP 
ERROR_VIO_EXISTING_POPUP 
ERROR_KBD_SMG_ONLY 
ERROR_KBD_INVALID_ASCIIZ 
ERROR_KBD_INVALID_MASK 
ERROR_KBD_REGISTER 
ERROR_KBD_DEREGISTER 
ERROR_MOUSE_SMG_ONLY 
ERROR_MOUSE_INVALID_ASCIIZ 
ERROR_MOUSE_INVALID_ MASK 
ERROR_MOUSE_REGISTER 
ERROR_MOUSE_DEREGISTER 
ERROR_SMG_BAD_ACTION 
ERROR_SCS_INVALID_CALL 
ERROR_SCS_SG_NOTFOUND 
ERROR_SCS_NOT_SHELL 
ERROR_VIO_INVALID_PARMS 
ERROR_VIO_FUNCTION_OWNED 
ERROR_VIO_RETURN 
ERROR_SCS_NOT_SESSION_MGR 
ERROR _VIO_REGISTER 
ERROR_VIO_NO_MODE_THREAD 
ERROR_VIO_NO_SAVE_RESTORE_THD 
ERROR_VIO_IN_BG 
ERROR_VIO_ILLEGAL_DURING_POPUP 
ERROR_SMG_NOT_BASESHELL 
ERROR_SMG_BAD_STATUSREQ 
ERROR_QUE_INVALID_WAIT 
ERROR_VIO_LOCK 
ERRPR_MOUSE_INVALID_IOWAIT 
ERROR_VIO_IVALID_HANDLE 
ERROR_KBD_INVALID_LENGTH 
ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_NO_MORE_HANDLE 
ERROR_KBD_CANNOT_CREATE_KCB441 
ERROR_KBD_CODEPAGE_LOAD_INCOMPL 
ERROR_KBD_INVALID_CODEPAGE_ID 
ERROR_KBD_NO_CODEPAGE_SUPPORT 
ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_FOCUS_ALREADY ACTIVE 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_INVALID_CODEPAGE 
ERROR_KBD_UNABLE_TO_FOCUS 
ERROR_SMG_SESSION_NON_SELECT 
ERROR_SMG_SESSION_NOT_FOREGRND 
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376 
77 
378 
379 
380 
381 
382 
383 
384 
385 
395 
396 
397 


398 
399 
400 
401 
402 
403 
404 
405 
406 
407 
408 
409 
410 
411 
412 
413 
414 
415 
416 
417 
418 
419 
420 
42] 
422 
423 
425 
426 
427 
428 
429 
430 
43] 
432 
433 
434 
435 
436 
438 
439 
440 
44] 
442 
443 
444 
445 
446 
447 
448 
449 
450 
451 


Invalid length for keyboard 
Invalid echo mode mask 

Invalid input mode mask 

Invalid parameters to DosMon 
Invalid device name string 
Invalid device name handle 
Buffer too small 

Buffer is empty 

Data record too large 

No mouse device attached 
Invalid frequency for beep 
Can’t find countrysys 

Can’t open countrysys 

Country code not found 
Country code not found 

Table truncated, buffer too small 
Selector type does not exist 
Selector type not in file 

Valid from session manager only 
Invalid asciiz length 

Vio deregister disallowed 

Popup not allocated 

Popup on screen (no wait) 

Valid from session manager only 
Invalid asciiz length 

Invalid replacement mask 
Kbdregister disallowed 
Kbdderegister disallowed 

Valid from session manager only 
Invalid asciiz length 

Invalid replacement mask 
Mouse register disallowed 
Mouse deregister disallowed 
Invalid action specified 

Init called more than once 

New screen group # 

Caller is not shell 

Invalid parms passed on 
Save/restore already owned 
Non-destruct return (undo) 
Caller not session manager 

VIO register disallowed 

No mode restore thread in SG 
No save/rest thread in SG 
Physical seletor requested in background 
Function not allowed during popup 
Caller is not the base shell 
Invalid status requested 

Nowait parameter out of bounds 
Error returnedfrom scrlock 
Invalid parameters for IO wait 
Invalid vio handle 

Invalid vio Length 

Invalid kbd handle 

Ran out of handles 

Unable to create kcb 
Unsuccessful codepage load 
Invalid codepage id 

No codepage support 

Keyboard focus required 
Keyboard focus exists 

Keyboard busy 

Invalid codepage 

Focus attempt failed 

Session is not selectable 
Parent/child session not foreground 

















ERROR_SMG_SESSION_NOT_PARENT 
ERROR_SMG_INVALID_ START MODE 
ERROR_SMG_INVALID_RELATED_OPT 
ERROR_SMG_INVALID_BOND_OPTION 
ERROR_SMG_INVALID_SELECT_OPT 
ERROR_SMG_START_IN_BACKGROUND 
ERROR_SMG_INVALID_STOP_OPTION 
ERROR_SMG_ BAD RESERVE 
ERROR_SMG_PROCESS_NOT_PARENT 
ERROR_SMG_INVALID_DATA_LANGTH 
ERROR_SMG_NOT_BOUND 
ERROR_SMG_RETRY_SUB_ALLOC 
ERROR_KBD_DETACHED 
ERROR_VIO_DETACHED 
ERROR_MOU_DETACHED 

- ERROR_VIO_FONT 
ERROR_VIO_USER_FONT 
ERROR_VIO_BAD_CP 
ERROR_VIO_NO_CP 
ERROR_VIO_NA_CP 
ERROR_INVALID_CODE_PAGE 
ERROR_CPLIST_TOO_SMALL 
ERROR_CP_NOT_MOVED 
ERROR_MODE_ SWITCH _INIT 
ERROR_CODE_PAGE_NOT_FOUND 
ERROR_UNEXPECTED_SLOT_RETURNED 
ERROR_SMG_INVALID_TRACE_OPTION 
ERROR_VIO_INTERNAL_RESOURCE 
ERROR_VIO_SELL_INIT 
ERROR_SMG_NO_HARD ERRORS 
ERROR_CP_SWITCH_INCOMPLETE 
ERROR_VIO_TRANSPARENT_POPUP 
ERROR_CRITSEC_OVERFLOW 
ERROR_CRITSEC_UNDERFLOW 
ERROR_VIO_BAD_RESERVE 
ERROR_INVALID_ADDRESS 
ERROR_ZERO_SELECTORS_REQUESTED 
ERROR_NOT_ENOUGH_SELECTORS AVA 
ERROR_INVALID_ SELECTOR 
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ERROR_SWAPPER_NOT_ACTIVE 
ERROR_INVALID_SWAPID 
ERROR_IOERR_SWAP_FILE 
ERROR_SWAP_TABLE_FULL 
ERROR_SWAP_FILE_FULL 
ERROR_CANT_INIT_SWAPPER 
ERROR_SWAPPER_ALREADY_INIT 
ERROR_PMM_INSUFFICIENT_MEMORY 
ERROR_PMM_INVALID_FLAGS 
ERROR_PMM_INVALID_ADDRESS 
ERROR_PMM_LOCK_FAILED 
ERROR_PMM_UNLOCK_FAILED 
ERROR_PMM_MOVE_INCOMPLETE 
ERROR_UCOM_DRIVE_RENAMED 
ERROR_UCOM_FILENAME_TRUNCATED 
ERROR_UCOM_BUFFER_LENGTH 
ERROR_MON_CHAIN_HANDLE 
ERROR_MON_NOT_REGISTERED 
ERROR_SMG_ALREADY_TOP 
ERROR_PMM_ARENA_MODIFIED 
ERROR_PMM_SET_FLAGS_FAILED 
ERROR_INVALID_DOS_DD 
ERROR_CPSIO_CODE_PAGE_INVALID 


452 
453 
454 
455 
456 
457 
458 
459 
460 
461 
462 
463 
464 
465 
466 
467 
468 
469 
470 
471 
472 
473 
474 
475 
476 
477 
478 
479 
480 
48] 
482 
483 
484 
485 
486 
487 
488 
489 
490 


32768 
32769 
32770 
S27 71 
S2i 72 
32773 
32774 
2770 
32776 
o2777 
32778 
32779 
32780 
32781 
32782 
32783 
32784 
32785 
32786 
32787 
32789 
32790 
65026 
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Not parent of requested child 

Invalid session start mode 

Invalid session start related option 
Invalid session bond option 

Invalid session select option 

Session started in background 

Invalid session stop option 

Reserved parameters not zero 

Session parent process already exists 
Invalid data length 

Parent not bound 

Retry request block allocation 

This call not allowed for detached pid 
This call not allowed for detached pid 
This call not allowed for detached pid 
No font available to support mode 
User font active 

Invalid code page specified 

System displays don’t support code page 
Current display doesn’t support code page 
Invalid code page 

Code page list is too small 

Code page not moved 

Mode switch init error 

Code page not found 

Internal error 

Invalid start session trace indicator 
Vio internal resource error 

Vio shell initialization error 

No session manager hard errors 
Dossetcp unable to set kbd/vio cp 
Error during vio popup 

Critical section overflow 

Critical section underflow 

Reserved parameter is not zero 

Bad physical address 

Must request at least one selector 

Not enough GDT selectors to satisfy request 
Not a GDT selector 


or 32768) 


Swapper is not active 

Invalid swap identifier 

I/O error on swap file 

Swap control table is full 
Swap file is full 

Cannot initialize swapper 
Swapper already initialized 
Insufficient memory 

Invalid flags for phys mem 
Invalid address of phys mem 
Lock of storage failed 
Unlock of storage failed 
Move not completed 

Drive name was renamed 
File name was truncated 

Bad buffer length 

Invalid chain handle 
Monitor not registered 
Specified screen group is top 
Arena modified - phys mem 
Update to arena header flags failed 
Invalid DOS mode device driver 
Code page is not available 
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ERROR_CPSIO_NO_SPOOLER 
ERROR_CPSIO_FONT_ID_INVALID 
ERROR_CPSIO_INTERNAL_ ERROR 
ERROR_CPSIO_INVALID_PTR_NAME 
ERROR_CPSIO_NOT_ACTIVE 
ERROR_CPSIO_PID_FULL 
ERROR_CPSIO_PID_NOT_FOUND 
ERROR_CPSIO_READ_CTL_SEQ 
ERROR_CPSIO_READ FNT_DEF 
ERROR_CPSIO_WRITE_ERROR 
ERROR_CPSIO_WRITE_FULL_ERROR 
ERROR_CPSIO_WRITE_HANDLE_BAD 
ERROR_CPSIO_SWIT_LOAD 
ERROR_CPSIO_INV_COMMAND 
ERROR_CPSIO_NO FONT SWIT 
ERROR_USER_DEFINED_BASE 


ERROR_I24_WRITE_PROTECT 
ERROR_I24_BAD_UNIT 
ERROR_I24_NOT_READY 
ERROR_I24_BAD_COMMAND 
ERROR_I24_CRC 

ERROR_I24_BAD_ LENGTH 
ERROR_I24_ SEEK 
ERROR_I24_NOT_DOS_DISK 
ERROR_I24_SECTOR_NOT_FOUND 
ERROR_I24_OUT_OF_PAPER 
ERROR_I24_WRITE_FAULT 
ERROR_I24_ READ FAULT 
ERROR_I24_GEN_FATLURE 
ERROR_I24_DISK_CHANGE 
ERROR_I24_WRONG_DISK 
ERROR_I24_UNCERTAIN_MEDIA 
ERROR_I24_CHAR_CALL_INTERRUPTED 
ERROR_I24_NO_MONITOR_SUPPORT 
ERROR_1I24_INVALID_PARAMETER 
ALLOWED_FAIL 
ALLOWED_ABORT 
ALLOWED_RETRY 
ALLOWED_IGNORE 

124 OPERATION 

124 AREA 


[24 CLASS 


65027 
65028 
65033 
65034 
65037 
65039 
65040 
65043 
65045 
65047 
65048 
65049 
65074 
65077 
65078 
OxF000 


O COnTM OT O09 DNDN © 


Ox0A 
0x0B 
0x0C 
0x0D 
OxOF 
0x10 
Ox11 
0x12 
0x13 
0x0001 
0x0002 
0x0004 
0x0008 
Oxl 
0x6 

01 if FAT 


Spooler not started 

Font id is not avail (verify) 

Error caused by switcher internal error 

Error caused by invalid printer name input 
Got code page req - cp switcher not initialized 
Pid table full- cannot activate another entry 
Received request for pid not in table 

Error reading font file control sequence section 
Error reading font file font definition block 
Error writing to temp spool file 

Disk full error writing to temp spool file 
Spool file handle bad 

Switcher load error 

Invalid spool command 

No font switch active 


10 if root DIR 


11 if DATA 
0x80 











Appendix D 


Introduction to Protected 
Mode Features of the 80286 
Processor 


The protected mode, the native mode of the 80286 CPU, gets its name from the built-in protection features of 
the processor. These are hardware features in the 80286 which make possible a virtual memory, multitasking 
operating system like OS/2. Such protection is required because in a complex operating system a fault in a single 
program cannot be allowed to corrupt the rest of the system—we need to protect the operating system from the 
applications. And when there are several applications active within the system at one time, we need to protect 
the code and data of one application from being corrupted by another. Only if both these conditions are met, 
can we be assured of a secure multitasking system. This appendix explains how OS/2 uses the protected mode 
features of the 80286 to implement such a system. 





Privilege Levels and Call Gates 


Under DOS, programs can directly address any memory location within the physical memory of the computer 
by specifying a valid address within RAM or the physical memory currently installed on the system. While this 
makes access to data segments and branches to code segments simple (assembler programs directly manipulate 
these values), it is quite easy for an application to corrupt the operating system by writing to a memory location 
that is used by the operating system causing the whole system to crash. OS/2 protects itself from such potentially 
destructive intrusions by taking advantage of the privilege level capability provided by the 80286 hardware (see 
Figure D.1). 

Under the privilege level concept, each segment of code running under OS/2 is automatically assigned a 
privilege level. The 80286 supports four hardware-recognized privilege levels arranged hierarchically from 0, 
the highest level, to 3, the lowest level. Code and data ata higher privilege level are inaccessible to code at a lower 
privilege level, but programs at a higher privilege level (numerically lower) have access to the lower level or the 
less privileged code and data. By placing the operating system at the highest privilege level, it is effectively isolated 
from the applications, while still allowing for the provision of system services by the operating system to its 
applications running at the lower privilege levels. 

Out of the four privilege levels provided by the 80286, only three are actually used by OS/2. Privilege level 
zero is reserved for the OS/2 kernel. Privilege level two is used by special routines such as device drivers which 
must have the ability to read and write directly to devices. Therefore this level is called the Input-Output privi- 
lege level or IOPL. Privilege level three is used by the application programs. Privilege level one is not used. 

The implementation of the privilege levels, as discussed so far, presents a problem in the provision of services 
to applications. Higher level code can manipulate lower level data. For example, the operating system can 
change the memory segments of an application or execute a routine defined in the application code. This type 
of “cooperation” is only applicable in one direction. Due to the protection of a higher privilege, low level 
applications cannot request system services or execute the predefined routines established by the operating 
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system. OS/2 solves this problem 
by implementing a mechanism 
known as a call-gate which allows 
Privilege level 3 application programs to getaround 
the hardware protection mecha- 
nism. In fact, the Application Pro- 
gram Interface (API) functions are 
a special group of call-gates pro- 


Privilege level 4 vided for level three applications 
; \ (but not for level two code). Call- 

Privilege level 0 gates allow lower level code to make 
branches into more protected code 

OS/2 at certain well defined entry points. 


Kernel If a thread attempts to directly 


access a memory segment which 
has a higher privilege level than its 
own, the CPU automatically issues 
a general protection exception number 
13. There is no need for the oper- 
Application ating system to do this checking. It 
Programs is done by the hardware which elimi- 
nates any negative effect on operat- 
ing system performance, as well as 
making it impossible for applica- 
tions to supercede the protection 
mechanism. Many exceptions under OS/2 are restartable errors. That is, they do not crash every program active 
within the system. OS/2 traps all protection exceptions generated by the CPU and takes steps either to rectify 
the problem or to terminate the execution of the offending thread. In most cases of protection violation, the 
offending thread is terminated. 


unused 





Figure D.1 Privilege Levels 


Indirect Memory Addressing 


While the privilege levels protect OS/2 from being corrupted by its applications, it is the zndirect memory 
addressing which protects the code and data of one application from accidently or maliciously being tampered 
with by another. Indirect addressing means that applications no longer have access to the physical addresses of 
the memory segments. Instead they use selectors which are pointers to descriptor tables—special tables in 
memory where the actual addresses of these memory segments are kept. Each process is assigned a descriptor 
table containing the physical memory segments to which the process currently has access. Any attempt by a proc- 
ess to address memory segments which are not part of its own descriptor table generates a protection exception. 
Later we’ll explain the mechanisms of this protection feature and how it makes it impossible for one process to 
gain unauthorized access to memory segments owned by another. In fact, this system works so well at protect- 
ing processes that special mechanisms have to be introduced by OS/2 to allow branches between processes (the 
task-gate) or the sharing of data segments amongst themselves (the shared memory API functions). 

As explained in Chapter 4, another benefit of indirect memory addressing is the provision of a virtual memory 
system that is completely invisible to application programs. Recall that each process within the system can address 
a memory space of 1 gigabyte which is then mapped onto a physical address space of up to 16 megabytes. Recall 
also that it is the job of a special module of the operating system called the Swapper to create the illusion that 
all the memory segments belonging to all the processes within the system are present in physical memory at the 
same time. The Swapper does this by moving memory segments back and forth between special files on the hard 
disk (called swap-files) and the physical memory as they are needed by the different processes. Segments that 
have not recently been used are swapped out to the hard disk to make room for segments that need to be accessed. 
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As you can see in Figure D.2 the 
use of indirect memory addressing 
allows for the efficient implemen- 


tation of the virtual memory con- Physical 
cept. Since each program does not MEsOeTy 
directly access memory, but merely Limit of Desrptor 

uses pointers to the descriptor table Segment Pieeaaeeeoey 


where the addresses are kept, a a ab 
program can continue to use the as) 
same selector to access a memory a 

segmenteven though the segment’s _— en 
location in physical memory may od displacement from 
change over time. The operating memory segment 
system merely has to change the 
value of the memory location stored 
in the descriptor table to provide a 
program with access to its memory 
segments in a virtual memory sys- 
tem. There is no need for the 
application to keep track of this. 


Target location 





Segment 





defined Memory 





Figure D.2 Indirect Memory Addressing 


implementation of Indirect Memory Addressing 


In the above sections, we have learned how the concepts of privilege levels and indirect memory addressing 
combined with separate descriptor tables respectively protect OS/2 from application programs, and isolate 
application programs from one another. We have also seen how the indirect memory addressing concept allows 
for the implementation of a virtual memory system that is completely invisible to application programs. In the 
proceeding sections, we learn how such concepts are actually implemented on the 80286 with selectors, 
descriptors, and descriptor tables. 


Selectors and Descriptor Tables 


Under OS/2, a program specifies the exact memory location it wants to access with a selectorand an offset. This 
is similar to the situation in real mode where a program specifies a base address and an offset from that base 
address to specify a memory location (see Figure 22.3). Protected mode addressing differs from real mode 
addressing in that the selector is not an actual physical memory address, but a selector pointing to a slot in a table 
kept in memory, called a descriptor table. Each slot in the descriptor table holds a descriptor which is a data 
structure containing the base address of the memory segment and additional information (i.e., the privilege level 
and the access rights to a segment). Under this scheme, every process within the system has access to a Local 
Descriptor Table (LDT) which contains the descriptors of the memory segments the process currently has access to. 

By restricting memory access to those segments specified by the LDT, the 80286 prevents the running process 
from addressing memory segments that do not belong to it. This protection feature is implemented at a hardware 
level. Every physical memory segment is addressed by a selector and an offset. If the selector is not valid, which 
means that it does not point to a descriptor on the LDT, a protection exception is generated by the 80286. 

By comparing Figures D.2 and D.3 , you can see that the function of the offset is the same in both real mode 
and protected mode. It is used to specify an exact memory location in bytes, calculated as an offset from the 
beginning of the memory segment. In real mode the beginning of the segment is specified by a base address, 
in protected mode, by a selector. 
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Local Descriptor Tables (LDT) and Global Descriptor Table (GDT) 


So far we have learned that OS/2 maintains a local descriptor table for each process. The LDT keeps all the 
descriptors which hold the physical addresses of the memory segments the process currently has access to. To 
address a memory segment, the process uses a selector which points to a descriptor on the LDT. 

Since the LDT is also a memory location requiring a physical address just like any other physical memory lo- 
cation, there must be another descriptor that contains the base address of the memory segment containing the 
LDT. This is precisely where the convention of maintaining two descriptor tables within the 80286 comes into 
play. You see, the Global Descriptor Table (GDT) contains descriptors that store the base addresses of the LDTs of 
every process within the system (see Figure D.4). 

At any given time there will only be two descriptor tables actively present within the system: one unique, 
unchanging GDT which contains the addresses of all the LDT’s, and an LDT which stores the memory segments 
belonging to the currently executing process. The GDT represents the address space that is common to all 
processes and OS/2, while the LDT represents the address space that is private to each application. 

There are two new registers in the 80286 which allow OS/2 fast access to descriptor tables, the Global Descriptor 
Table Register (GDTR) and the Local Descriptor Table Register (LDTR) . These always contain, respectively, the base 
address of the GDT and the LDT of the currently executing process. When OS/2 is loaded, a global descriptor 
table is constructed in memory and its location is stored in the GDTR. The contents of the GDTR never change 
during the operation of OS/2. But whenever a thread of another process is switched to the active mode, the 
contents of the LDTR must change to reflect the base address of the current process’ LDT. To load the LDTR 
with anew value, the LLDTR (Load LDT Register) instruction must be used. This instruction, however, can only 
be executed by 0 level code, which means that only OS/2 can change a descriptor table. 

Because application programs are not allowed to issue the LLDTR instruction, they are not able to access 
memory segments belonging to another process. This is what is meant by the protection of code and data between 
processes. In order for processes to share information and resources amongst themselves, OS/2 provides mecha- 
nisms that get around the protection afforded by maintaining separate descriptor tables for each process. These 
were precisely the shared memory 
Physi and interprocess communications 

ysical . ; ; 
Memory API functions discussed in Chap- 
ters 3 and 4. 

If the preceding discussion was 
understood, enough is known to 
eee ee understand the basic hardware 

Seamen shige tanga features of the 80286 that OS/2 has 
gaa at a used to establish virtual memory 
—— and protection for code and data of 

ee arunning application. The remain- 
———— ing sections are a detailed discus- 
sion of the way a single thread is 
executed within the 80286. First, 
we'll explain the selector and its 
counterpart, the descriptor, and 
their relationship to the operation 
of the segment registers in protected 
mode. This brings home the extent 
of the “protection” provided by 
protected mode as well as enabling 
one to understand the mechanisms 
by which transfer of control is ef- 
fected in a single process, both at 
the same privilege level and be- 
tween privilege levels. 


Base Address 





Figure D.3 Real-mode Memory Addressing 
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Segment Registers 


The most important distinction to remember between selectors and descriptors is that selectors are tokens 
which are passed through the operating system and are used by application programs to identify memory 
segments. The information in the descriptor pointed to by the selector, even though it contains the information 
about the actual location of a memory segment, is absolutely inaccessible to application programs. The program, 
however, has control of the value of the selectors by loading the value into one of the segment registers. 
Combined with an offset, the selector represents an entry point for a code segment or a memory location for data 
segments. Everytime a new selector is loaded into one of the segment registers, the 80286 simply loads the value 
of the descriptor into a special cached, or hidden, part of the segment register after protection checking (see 
Figure D.5). 

The 80286 provides four segment registers which can be manipulated by application programs. The contents 
of these registers indirectly represent the memory segments that are being accessed within the system at any given 
time. They represent the memory segments being used by the currently executing thread. There are registers 
for the code segment that is being executed (the CS register), two data segments (DS and ES registers), and the 
segment used by the program stack (SS register). Three of these registers, the data segment (DS) register, the 
extra segment (ES) register, and the stack segment (SS) register, can be directly manipulated by programs. In 
other words, a program can specify a new data segment, an extra data segment, or a stack segment simply by 
loading a new selector into any one of these registers. The contents of the code register, on the other hand, can 
only be changed by issuing a JMP or CALL instruction. This is because changing the value of the selector in the 
CS register effects a transfer of control between code segments, and it is necessary to control such a branch for 
protection reasons. 

Because the code segment register contains the location of the currently executing thread, the CS register 
can be considered as the master register governing the thread’s execution. In fact, the privilege level of the entire 
thread is defined by the privilege level of the current code segment. The privilege level of any segment is defined 
by a value stored on the descriptor, 


the DPL—descriptor privilege level. Public Address 
When the CS register points to a PReOe  gvalnive data 
to all processes 


descriptor, the DPL of this descrip- win he 
tor takes another meaning. It be- 
comes the current privilege level (CPL) 
which represents the privilege level 
of the executing thread. The 80286 
uses the CPL to check whether any 
attempt to access a memory seg- 
mentconforms to the privilege level 
rule (explained subsequently). Due 
to its importance in the protection 
mechanism, the CPL is accessible 
only to OS/2. 

So we see that a segment regis- 
ter in protected mode has two parts: 
a program visible part (two bytes 
long) which contains the selector 
specified by the program, and a 
hidden, program invisible part, 
which contains the information 
from the desired segment’s descrip- 
tor. This hidden cached field in the 
segment register is eight bytes long Scene Process 1 
and is loaded into the segment 


register only if the desired segment Figure D.4 OS/2 Address Space 


Process 2 
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is permitted according to the privi- 
Program: Melble Program Invisible lege level rules. In order for the de- 

Ss SEGMENT f scriptor of the desired segment to 
be cached, both of the following 


SELECTOR conditions must be true: 
specified by program 


Register 





Figure D.5 Segment Register 


* The privilege level of the desired memory segment must be the same or lower than the CPL of the 
system. If the desired memory segmentis to be placed in the Stack Segment register, then the privilege 
level of the desired segment must be the same as the CPL’. 


" The desired segment must be of a type that can be validly loaded in the target segment register. For 
example, the selector for a data segment may not be loaded into the code segment register. 


The tests for these conditions are performed by the hardware itself making for fast protection checking and 
the impossibility of circumventing the protection mechanism as would be the case if the testing were carried out 
with software. 


"As explained throughout this appendix, the address of the desired memory segment is not stored in the register but rather a 
selector, which points to a descriptor containing the base address of the desired memory segment, is placed in the register. For 
the sake of economy, we use the term “store” or “place” to represent this complex chain of events. 
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ABORT action parameter, 291 
Access modes, file, 384, 391 
Accuracy of timer functions, 279 
ACK scan code, 800 
Action codes and parameters 
for DosCWait, 52-53 
for DosOpen, 388 
for DosSetSigHandle, 93-94 
for errors, 290-291 
Active threads, 11 
Adapters, 514-516 
direct manipulation of, 643 
driver for, 17 
IOPL functions for, 773 
modes for, 520 
and sessions, 12-14 
Add menu option, 495 
\ALIGNMENT switch (LINKER), 347 
Alloc() function (C), 165 
Allocflags parameter (DosAllocSeg), 176 
ALREADY error class, 290 
Alt-Esc, base shell for, 494-495 
Alt keys, 575, 581 
Alt-Shift keys, 575 
ANSI support functions, 319, 511, 569-571 
ANSICALL.DLL library, 319 
API. See Application Program Interface func- 
tions; FAPI 
API.LIB library, 340 
APPERR error class, 289 
Application Program Interface functions, 2, 15- 
17 
conversion of, 824-825 
library for, 318-319 
See also FAPI 
Applications 
error class for, 289 
interface for, 513 
linking of, 334-342 
PIDs for, 85 
ARF (Automatic Response File), 358 
Argnum argument for EXPORTS statement, 
331 
Arguments. See Parameters 
ASCII characters 
display functions for, 511-512 
input functions for, 579-583 
and keyboard, 575 
and shift states, 591 
and video buffer, 644, 654 
ASCII files with MSGBIND, 312-314 
Assembly language programs 
conversion of, 825-827 
and DosSetSigHandler, 258 
for dynamic link libraries, 337-339 
error codes for, 287 
exception handlers in, 295 
and memory suballocation, 191 
and stacks, 15-16 
Asterisks (*) as wild card characters, 469 
Asynchronous child processes, 30, 37 
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Asynchronous communication port, 706 
break processing of, 759-760 
dcb parameters for, 766-771 
device name for, 381, 386 
line characteristics of, 743-753 
logical flow with, 756-758 
queues for, 753-756 
status of, 760-766 
Asynchronous timer functions, 277-278, 280- 
283 
At sign (@) character 
with ARF files, 358 
with BIND utility, 342 
Atomic instructions and operations, 111, 121 
Attributes 
for characters, 538-539 
reading and writing of, 541-546, 548- 
549, 551-552 
and video buffer, 644, 654 
for cursor, 535 
for devices, 450, 722 
in file searches, 476-477 
for files, 382-390, 444, 464-466 
for segments, 322, 327-330 
AUTH error class, 289 
Automatic Response File, 358 
B 
Background color, 531 
Background pop-ups, 646-653 
Background processes, 31, 492-494 
and signals, 256 
Background sessions, 13, 489-491, 510 
BadDynLink, 340 
BADFMT error class, 290 
Bank switching, 1 
Base Mouse Subsystem, 599 
Base shell, 494 
Baud rate functions, 744-745 
Beginning of file, 391 
BIND utility, 23, 339-342 
BIOS calls 
conversion of, 823 
keyboard, 575 
supported by compatibility box, 828-829 
BIOS Parameter Block, 722-725 
Bit-mapped mouse pointer image, 627-628 
BKSCALLS.DLL library, 319, 573 
Blinking foreground, 531-532 
BMS (Base Mouse Subsystem), 599 
BMSCALLS.DLL library, 319 
BOF (beginning of file), 391 
Boot sector, 716 
Bound sessions, 501-504 
BPB (BIOS Parameter Block), 722-725 
Break on IOCTL function, 759 
Break off IOCTL function, 760 
Breakpoint Interrupt vector, 294 
Buffers, 13 
for asynchronous adapters, 743 
for device monitors, 788, 794-803 
for disk operations, 394, 413, 434-435 


flushing of, 43 

for hot-key sequences, 712 
for keyboard, 574 

for pipes, 151, 153 

See also Logical buffers 


. Buttons, mouse, 602, 638 


BVSCALLS.DLL library, 319 
C 


C compilers and programs 
command-line parameters for, 33 
conversion of DOS programs in, 824 
and DosSetSigHandler, 258 
for dynamic link libraries, 337-338 
error codes for, 288 
exception handler for, 295 
and file I/O, 380 
memory models for, 182 
parameter pushing with, 16-17 
selectors and offsets for, 172-174 
termination of threads by, 43 
thread function restrictions on, 71-73 

CALL instructions 
for API functions, 15 
external, 315 
long references created by, 345 
with run-time dynamic linking, 366, 371 

Calling threads, 71 

CANT error class, 290 

CapsLock key, 575, 582, 594 

Carry flag for errors, 287 

Case of letters, LINKER switch for, 353 

CD command, 439-440 

Cell strings, 541 

CGA. See Color graphics adapters 

Chains 
of bound sessions, 502 
monitor, 786-789, 791-793, 806 

Change device parameters IOCTL function, 722- 
726 

Character device monitors, 19, 492, 646, 785 
architecture of, 786-789 
development of, 789-803 
time windows for, 791, 803-804 

Characters 
attributes of, 538-539 
displaying of, 540-550 
flag for, 581 

CHDIR command, 439-440 

Child processes 
arguments received by, 35 
creation of, 30 
file handles for, 450 
semaphores for, 117, 119 
spawning of, 27 
standard devices for, 414-415 
system resources inherited by, 33-34 
termination of, by parent, 47 

and video screen, 31 
Child sessions 

creation of, 496 

termination of, 499-500 
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Classname argumentfor SEGMENTS statement, 
328 
Clear interrupt capability, 775 
Clearing 
of screen, 559 
of semaphores, 113, 120 
CLI instruction, 777, 780, 826 
Clock ticks and timer accuracy, 279 
Closing 
of device monitors, 789, 804, 811-812 
of files, 386, 389-390 
of queues, 227-228, 230-232 
of semaphores, 112-113, 120 
Clusters, disk, 424-425, 444 
CMD.EXE file, 27, 33, 90 
CmdOffset, 60 
Cntrl-Break, 255, 590 
interrupt for, 90, 94 
and keyboard monitors, 801 
Cntrl-C, 255, 590 
interrupt for, 90, 94 
and keyboard monitors, 801 
Cntrl-ESC for program selector, 494-495 
Cntrl keys, 575, 581-582 
Cntrl-P, 590 
Cntrl-S, 590 
Code-page switching functions, 511 
Code segments, re-entrant, 317, 333 
CODE statementin module definition files, 321, 
323-325 
\CODEVIEW switch (LINKER), 351 
Collision area for mouse, 605-606, 633-635 
Collision_Area structure, 634 
Colons (:) in message headers, 299 
Color graphics adapters, 515-516 
colors for, 539 
direct manipulation of, 645, 660 
font size with, 678 
memory for, 644 
modes for, 520-521 
pages supported by, 654 
palette for, 527-528 
resolution of, 524-525, 644 
Color mode, 523 
Color monitors, 515, 517 
Colors, 531 
display, 521, 523, 539 
for pixels, 644 
See also Palette 
Column 
of cursor position, 532-533 
of display, 520, 524 
of mouse position, 603 
COM ports and compatibility box, 829 
Combining segments, 343-344 
COMERR structure, 761, 763 
COMMAND.COM file, 22-23 
Command-line 
and DosGetEnv, 60 
linking from, 356-358 
parameters on, 33, 60 
Commas (,) for command-line linking, 358 
Common combine type, 344 
Communication error IOCTL function, 762- 
764 
Communication event information IOCTL 
function, 761-762 
Communication event status word, 760-762 
Communication status IOCTL function, 764 
765 


Communications programs 
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IOCTL functions for, 706 
multiprocessing for, 26 
See also Asynchronous communication port 
Compatibility and multitasking, 1 
See also Real mode 
Compatibility box, 22-23, 823, 827-830 
rmsize parameter for memory for, 171 
Compiler memory allocation functions, 165 
COMx devices, 381, 386 
IOCTL support for, 707 
for mouse drivers, 601 
CON device, 381, 414 
CONFIG:SYS file 
for IOPL segments, 775 
for memory management, 171-172 
mouse driver parameters in, 601-602 
thread priority parameters in, 80 
Threads parameter in, 29 
Configuration of video system, 514-532 
Connectivity and Presentation Manager, 512 
Console, device name for, 381 
Context switching, 9-11 
Control functions 
device I/O. 
file, 486-487 
Control key, 581 
Conversion of DOS applications, 823-832 
Cooked keyboard mode, 255, 590-592 
Coordinates, mouse, 615, 634-635 
Coprocessors and exception vectors, 296 
COPY command, 486 
Countdown timer functions, 277 
\CPARMAXALLOC switch (LINKER), 349 
Create options for DosOpen, 388-389 
Creation 
of dynamic link libraries, 337-342 
of files, 387, 415-416, 426, 444, 455-459 
of processes, 34-43 
of queues, 227-229 
of semaphores, 112-113, 117-119 
of sessions, 495-499 
of subdirectories, 440-441 
of threads, 71-75 
Critical sections, 87 
compared to semaphores, 125-126 
for IOPL segments, 777 
for mutual exclusion, 103-110 
with video functions, 680 
Current BPB, 722-723 
Current communication status word, 761, 764 
765 
Current directory, 439-440 
Current size of receive queue IOCTL function, 
754-756 
Currentsize of transmit queue IOCTL function, 
755-756 
Cursor 
control functions for, 511-512, 532-537 
representation of, 534-535 
with VioWrtTty, 540 
Cylinders, drive, 722, 733 
D 
DASD (direct access system device), 386 
Data 
protection of, 380 
on queues, 226-227, 233, 241-242 
sharing of, 21, 26 
streams, 379 
transfer of, 88, 149-164, 197-198, 494 
See also Asynchronous communication port 


See IOCTL functions 


Data bits, IOCTL functions for, 746-748 
Data carrier detect signal, 743 
Data segments, LINKER switch for, 349 
DATA statementin module definition files, 322, 
325-327 
Data terminal ready signal, 743-744, 748-753 
Date 
file creation, 426, 444, 456 
functions for, 273-276 
in Global Descriptor Segment, 67-68 
DateTime structure, 274 
Day 
in DateTime structure, 274 
of file creation, 456 
in Global Descriptor Segment, 67-68 
in SetDateTime structure, 275 
DBCS. See Double-byte character set 
DCB structure, 769 
DCD signal, 743 
Debugging 
and DosExecPgm, 37 
interrupt for, 294 
LINKER switches for, 350-351 
Decimal numbers in LINKER switches, 346-347 
.def extension, 320, 339 
Default actions for exceptions, 293, 295 
Default directory, 469 
Default drives, 420 
Default exception handlers, 8 
Default keyboard handle, 576 
Default logical keyboard, 577 
Default signal handling, 90, 255 
DefFile parameter for command-line linking, 
357 
Delays, typematic, 709-710 
Deny none sharing mode, 391 
DESCRIPTION statement in module definition 
files, 321, 323 
Descriptor tables, 3-4, 166 
Descriptors, privilege level stored in, 7 
Detached processes, 34-36, 38, 492 
Determine baud rate IOCTL function, 745 
Determine device control block IOCTL func- 
tion, 771 
Determine device parameters IOCTL function, 
726-728 
Determine frame control IOCTL function, 738- 
740 
Determine infinite retry status IOCTL function, 
736-738 
Determine keyboard type IOCTL function, 710- 
Tad 
Determine modem control input signal IOCTL 
function, 752-753 
Determine modem control outputsignal IOCTL 
function, 750-752 
Determine parity, stop, and data bits IOCTL 
function, 747-748 
Determine physical device parameters IOCTL 
function, 733-735 
Device control block parameter functions, 766- 
77) 
Device monitors. See Character device monitors 
Devices, 17-19, 379-380, 681-683 
closing of, 386, 389-390 
drivers for, 17, 774-775 
failure class for, 289 
keyboard subsystem for, 696-699, 702-703 
message output to, 307-308 
mouse subsystem for, 699-702 
naming of, 381 








opening of, 382-391 
reading of, 392-393 
standard, 414416 
threads for, 26-27 
video subsystem for, 683-695 
writing to, 393-395 
See alsoAsynchronous communications port; 
IOCTL functions 
DI signal, 743 
Dialog Manager, 514 
Direct access system device, 386 
Direct disk I/O services, 419 
Direct manipulation of video buffers, 643, 645 
logical, 654-659 
physical, 660-668 
Directories 
entries in, 444, 715-716 
management of, 417-418, 437-444 
moving files to, 486 
searching of, 469 
for SWAPPER.DAT, 171-172 
Disabled state mouse mode, 600, 607-608 
Discardable memory segments, 168, 170, 175, 
177-178 
DISK error locus parameter, 291 
Disks and disk drives, 417-422 
I/O with, example of, 402-411 
IOCTL functions for, 707 
locking of, 716-718, 731-733 
for memory swapping, 167 
parameters for, 423-432 
partitioning of, 432-437 
space on, 425, 722-728 
track functions for, 733-735 
See also Directories; Logical drives 
Dispatcher, 11-12, 14 
monitor, 788 
and priority classes, 79-80 
Displayed cells, 538 
Divide Error Exception vector, 294-295 
.dll files, 318, 320, 336 
DLYRET action parameter, 290 
DOS and OS/2, 22-23, 823-832 
DosAllocHuge function, 178, 182-185, 198, 208 
DosAllocSeg function, 175-178, 195, 198, 208, 
233, 235 
DosAllocShrSeg function, 173, 178, 191-192, 198- 
202 
DosBufReset function, 394, 413 
DOSCALL1.DLL file, 318 
DOSCALLS.DLL library, 318-319, 335-336 
and BIND utility, 340 
for run-time linking, 371 
DosChDir function, 440 
DosChgFilePtr function, 382, 386, 395-397 
DosCLlAccess function, 777-778, 780 
DosClose function, 386, 389-390, 413 
DosCloseQueue function, 227-228, 230-232 
DosCloseSem function, 113, 117, 120 
DosCreateQueue function, 227-229, 235 
DosCreateSem function, 112, 117-119 
DosCreateThread function, 28, 45, 71-75 
DosCWait function, 30, 36, 43, 87 
and DosKillProcess, 47 
for synchronization of processes, 51-60 
DosDelete function, 487 
DosDevContfig function, 296 
DosDevIOCTL function. See IOCTL functions 
DosDupHandle function, 158-163, 415-416 
DosEnterCritSec function, 107-110 
DosErrClass function, 289-292 


DosError function, 288, 293, 297-298 
DosErrorClass function, 287-292 
DosExecPgm function, 27, 32 

for child processes, 30 

for passing arguments, 33-34 

with pipes, 153 

and pop-ups, 647 

for processes, 34-43, 85-86 

for semaphore names, 113 

and thread termination, 45 

and VioRegister, 683 
DosExit function, 27, 30, 43-44 

and DosExecPgm, 39 

for threads, 71, 73 
DosExitCritSec function, 107-110 
DosExitList function, 43-47, 120 
DosFileLock function, 411-413 
DosFindClose function, 469, 474, 478 
DosFindFirst function, 469, 474477 
DosFindNext function, 469, 474-475, 477478 
DosFlagProcess function, 89, 91, 95-96 
DosFreeFocus function, 576 
DosFreeMod function, 365-366, 369 
DosFreeSeg function, 172, 175, 178-179, 200, 

202, 233-235 
DosGetDateTime function, 273-275 
DosGetEnv function, 34, 60-63, 469n 
DosGetHugeShift function, 182-183, 185, 208 
DosGetInfoSeg function, 34, 66-69, 279 
DosGetMachineMode function, 70, 340 
DosGetMessage function, 298-304, 311, 314 
DosGetModHandle function, 365-367 
DosGetModName function, 365, 370-371 
DosGetPID function, 30, 34, 65-66, 69, 71 
DosGetProcAddr function, 365-366, 371-372 
DosGetPrty function, 69, 82-83 
DosGetResource function, 365, 372-374 
DosGetSeg function, 175-176, 198, 208, 217, 233 
DosGetShrSeg function, 198, 200, 202-203 
DosGetVersion function, 69-70 
DosGiveSeg function, 175-176, 183, 198, 208- 

210, 233-234 
DosHoldSignal function, 257-259 
DosInfoSeg function, 279 
DosInsMessage function, 299-301, 305-307 
DosKillProcess function, 30, 47-51, 90 

and DosExecPgm, 40 

and DosStopSession, 499 

and SigTerm, 255-256 
DosLoadModule function, 365-369 
DosLockSeg function, 175, 177-178 
DosMakePipe function, 151, 153-158 
DosMemAvail function, 172-174, 182 
DosMkDir function, 440-441 
DosMonClose function, 789, 804, 811-812 
DosMonOpen function, 788, 804-806 
DosMonRead function, 789-790, 794, 796, 804, 

808-810 
DosMonReg function, 788, 790, 792, 794, 804, 

806-808 
DosMonWrite function, 788-790, 794, 804, 810- 

811 
DosMove function, 486 
DosMuxSemWait function, 113-114, 117, 128, 

132-138 

with timer functions, 280n 
DosNewSize function, 444, 467-468 
DosOpen function, 382, 386-389 

for logical drives, 715 
DosOpenQueue function, 227, 230-231, 235 
DosOpenSem function, 113, 117, 119-120 
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DosPeekQueue function, 232, 235, 237-241 
DosPhysicalDisk function, 419, 432-437, 706, 

715 
DosPortAccess function, 778-780 
DosPurgeQueue function, 232, 242 
DosPutMessage function, 301, 307-308 
DosQCurDir function, 439-440 
DosQCurDisk function, 419-423 
DosQFHandState function, 444-446 
DosQFileInfo function, 444, 455-457 
DosQFileMode function, 464465 
DosQFSInfo function, 394, 419, 424-427 
DosQHandType function, 153, 450-455 
DosQueryQueue function, 232, 241-242 
DosQVerify function, 444-445, 468 
DosRead function, 382, 386-387, 392-393 

and asynchronous port, 754 

for parallel printer, 735 

with pipes, 152 

with queues, 227 

standard device for, 414 
DosReadAsync function, 277 

and asynchronous port, 754 

for parallel printer, 735 

with pipes, 152 
DosReadQueue function, 232-233, 235, 237-241 
DosReAllocHuge function, 186-187 
DosReAllocSeg function, 175, 178-180, 182, 192, 

195 
DosResumeThread function, 28, 76, 87 
DosRmDir function, 441 
DosScanEnv function, 63-65, 469n 
DosSearchPath function, 469-473 
\DOSSEG switch (LINKER), 351 
DosSelectDisk function, 419-420, 423 
DosSelectSession function, 496, 500-501 

and screen saving, 669 

and VioScrLock, 661 
DosSemClear function, 113, 121, 123 
DosSemRequest function, 113-114, 123-125, 132 
DosSemSet function, 113, 121 
DosSemSetWait function, 113, 129-131 
DosSemWait function, 113-114, 127-129 
DosSetDateTime function, 273, 275-276 
DosSetFHandState function, 444, 448-449 
DosSetFileInfo function, 444, 455, 457-458, 461- 

464 
DosSetFileMode function, 464467 
DosSetFSInfo function, 419, 427-428 
DosSetMaxFH function, 390 
DosSetPrty function, 80-82 
DosSetSemWait function, 114 
DosSetSession function, 501-504 
DosSetSigHandler function, 48, 293 

and DosStopSession, 499 

for flag manipulation, 89-95 

and IPC, 256-258 
DosSetVec function, 288, 293, 295-297 
DosSetVerify function, 445, 468 
DosSleep function, 76, 257, 277 
DosStartAsync function, 277-278, 283 
DosStartSession function, 496-499 

and screen saving, 669 
DosStartTimer function, 279, 283 
DosStopSession function, 496, 499-500 
DosStopTimer function, 280-281 
DosSubAlloc function, 190-193, 195 
DosSubFree function, 190-191, 193-195 
DosSubSet function, 191, 195-197 
DosSuspendThread function, 28, 76, 87 
DosSystemService function, 38, 494 
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DosTimerAsync function, 280-281 
DosTimerStart function, 277-278, 281-282 
DosTimerStop function, 277, 282-283 
DosUnlockSeg function, 175, 177-178 
DosWrite function, 382, 386-387, 393-395 
for parallel printer, 735 
with pipes, 152 
with queues, 227 
standard device for, 414 
and transmit queue, 753 
DosWriteAsync function, 277 
for parallel printer, 735 
with pipes, 152 
and transmit queue, 753 
DosWriteQueue function, 230, 235-237 
Double-byte character set, 575 
interim flag for, 593 
and keyboard monitors, 798 
reading of, 580-581, 588 
Double-clicking of mouse, 603 
Double Exception Detected vector, 294 
Downloadable fonts, 678 
DPATH OS/2 variable, 469 
Drive maps, 420 
Drives. See Disks and disk drives; Logical drives 
\DSALLOCATE switch (LINKER), 349 
DTR (data terminal ready) signal, 743-744, 748- 
753 
Dummy device, 381 
Dump bucket, 381 
Dump key and keyboard monitors, 799-800 
Dynamic linking and dynamic link libraries, 19, 
315-320 
and API functions, 15 
creation of, 337-342 
example of, 359-362 
for IOPL segments and device drivers, 774 
for keyboard functions, 573 
LINK for, 342-359 
load-time, 362-364 
module definition files for, 320-334 
for OS/2 applications, 334-336 
run-time, 364-377 
for video subsystem, 510-511, 645 
E 
Echo keyboard mode, 591-592 
Edge triggered semaphore functions, 114-117, 
132 
EGA. See Enhanced graphics adapters 
8088 programs, conversion of, 825-827 
8514A Display Adapter, 600 
80386 and IOPL segments, 778 
Elapsed time count, 279 
End of file, 391 
End-of-line termination character, 587 
Enhanced color monitors, 515-517 
Enhanced graphics adapters, 515-516 
attributes for, 539 
colors for, 522, 539 
direct manipulation of, 645, 660 
font size with, 678 
memory for, 644 
modes for, 520-521 
pages supported by, 654 
palette for, 528-530 
resolution of, 524, 644 
switching modes in, 670 
Entryname argument, 330-331 
Entryordinal argument, 330 
Environment block, 31-32, 469 
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and data transfer, 494 
pointer to, 60-63 
searching through, 63-65 
variables in, 35, 38 
EnvSeg, 60 
EOF (end of file), 391 
Error_Mon_Buffer_Empty error, 809 
Error_Mon_Invalid_Parms error, 809-810 
Error_Not_Enough_Memory error, 810 
Errors and error handling, 287-292 
action parameters for, 290-291 
classes of, 289-290 
code values for, 287-288 
communication, 761-764 
edge triggered semaphores for, 116 
for exceptions, 293-297 
for hard errors, 297-298 
locus parameters for, 291 
and message retrieval facility, 298-314 
STDERR device for, 414 
See also Exceptions 
Eventinfo structure, 616 
Events, mouse, 601-603, 606, 609-623 
Exceptions, 287-288 
handling of, 293-297 
and memory swapping, 7-8 
protection, 7 
See also Errors and error handling 
Exclusive semaphores, 117-118 
.EXE as default extension, 335 
.EXE (executable) files 
linking of, 320, 342 
for messages, 312 
Executable parameter for BIND utility, 341 
Execute argument for CODE statement, 324 
Execution control functions, 21-22 
Execution environment, 489-508 
Execution modes of child processes, 37-38 
Execution modules, 15 
ExeFile parameter for command-line linking, 
357 
\EXEPACK switch (LINKER), 349-350 
Expanded memory system, | 
EXPORTS statement 
for IOPL segments. 776 
in module definition files, 322, 330-332, 337 
for run-time dynamic linking, 364-365, 371 
and VioRegister, 686 
Extendability of OS/2, xiii 
Extended ASCII code, 575 
reading of, 580, 588 
Extended memory with DOS, xii 
Extensions, file, 381 
default, 320 
in directory, 444 
for messages, 299, 301 
for module definition files, 318 
External events, handling of, 256-272 
External libraries, linking of, 316 
External message retrieval facility,, 288 
External references, 315 
and dynamic linking, 317 
LINKER for, 343-345, 354 
F 
FAPI (family API applications), 23, 830-831 
creation of, 339-342 
for mouse, 640 
\FARCALLTRANSLATION switch (LINKER), 
347-348 
FAT (File Allocation Table), 417, 419, 715-716 


FIFO lists and queues, 225, 227, 229, 234 
File Allocation Table, 417, 419, 715-716 
Files, 28, 379-380, 417-418 
buffers for, 413 
closing of, 386, 389-390 
control functions for, 486-487 
for data transfer, 149 
deletion of, 487 
directory entry for, 444 
disk, 397-411 
handles for. See Handles, file 
naming of, 381 
opening mode and attributes for, 382-391 
pointers for, 395-397 
protection of, 411-413 
reading of, 392-393 
searching for, 469-486 
sharing mode for, 384-385, 391 
standard, 414416 
status functions for, 444468 
STDIN and STDOUT as, 494 
writing to, 393-395 
First-in-first-out lists and queues, 225, 227, 229, 
234 
Fix-up overflow error message, 344 
Flag registers, DOS vs. OS/2, 827 
Flags for signals, 87, 89-103, 255 
Floppy drives, xi 
Flow control for devices, 770 
Flush record with device monitors, 796 
Flushing of buffers, 43, 579, 589-590 
Focus, keyboard, 574-576 
Fonts, control of, 511-512, 677-680 
Foreground color, 532, 539 
Foreground processes, 31 
and signals, 256 
Foreground sessions, 13, 489-491, 510 
Foreign languages 
characters for, 575 
and code-page switching, 511 
message retrieval facility for, 288 
Format, error class for, 290 
FORMAT command, 424 
Format and verify track IOCTL function, 728- 
731 
Formatting device drivers, 722 
FP_OFF() macro (C), 173-174 
FP_SEG() macro (C), 172-174 
Fragmentation of memory, 169-170 
Frame address, 343 
Free() function (C), 165 
FSInfoBuf data structure, 425-426 
Full-draw support mouse mode, 600, 607 
G 
GDDM (Graphical Display Data Manager), 512 
GDT (Global Descriptor Table), 45 
GDTR (Global Descriptor Table Register), 4 
General failure error, 769 
General Protection vector, 295 
Get printer status IOCTL function, 741-742 
Get Session Manager hot-key IOCTL function, 
712-715 
Getting the keyboard focus, 575-576 
Global data and threads, 28 
Global descriptor, date and time information in, 
273, 279 
Global Descriptor Segment 
and DosGetInfoSeg, 66 
structure for, 67-68 
Global Descriptor Table, 4-5 








Global Descriptor Table Register, 4 
Global variables 

for data sharing, 21 

as flags, 89 

for inter-process signalling, 148 

for IOPL segments, 777 

and mutual exclusion, 104 
GMT (Greenwich Mean Time) 

in DateTime structure, 274 

in Global Descriptor Segment, 67-68 

in SetDateTime structure, 275 
Grandchild processes, spawning of, 27 
Grandchild sessions 

binding of, 502 

and DosStopSession, 499 
Graphical Display Data Manager, 512 
Graphics 

IOPL functions for, 773 

mouse in, 600, 607 

Presentation Manager for, 514, 643-645 
Graphics modes, 521, 523 

with EGA, 670 

mouse pointer for, 625 
Graphics screens, saving of, 670 
Greater than sign (>) with message files, 312 
Greenwich Mean Time information 

in DateTime structure, 274 

in Global Descriptor Segment, 67-68 

in SetDateTime structure, 275 
Group concept, LINKER for, 344, 354 


H 
Handlers, exception, 8 
Handles 
for device monitors, 804-806 
disk, 432-433 
tor DosDevIOCTL, 706 
file, 379, 382, 386, 390, 444 
duplication of, 415-416 
inherited, 34, 450 
keyboard, 576-577 
module, 365-367 
mouse, 605, 608-609 
for parallel ports, 735 
for pipes, 151, 153 
for queues, 226, 228, 230 
for semaphores, 111-112, 117-119, 121, 124 
Handshaking modes, 769 
Hanging threads, 44 
Hard disk drives, xi 
partitioning of, 420-421, 423-424, 432-437 
for segment storage, 167 
subdirectories on, 437-438 
See also Logical drives 
Hard errors, 287-288 
DosExecPgm abort code for, 40 
handling of, 297-298 
pop-ups for, 491, 646 
Hardware I/O ports, 773 
Hardware interrupts, 293, 777-778 
Hardware status, 494 
Headers 
of executable files for memory allocation, 
27 
for pipe records, 152 
Heads, disk, 733 
HEAPSIZE statement in module definition files, 
922, O08 
Help message type, 299 
\HELP switch (LINKER), 347, 351 
Hexadecimal numbers, 346-347 


Hidden files, 382, 386 
Hidden sessions, 496 
High-intensity characters, 532 
High-level languages 
conversion of DOS in, 824 
memory allocation in, 165 
memory suballocation in, 191 
\HIGH switch (LINKER), 350 
Horizontal resolution, 520, 524 
Hot-key sequences, xii, 646 
base shell for, 494 
IOCTL function for, 712-715 
and keyboard monitor, 800 
with mouse, 638-639 
Hours 
in DateTime structure, 274 
of file creation, 426, 456 
in Global Descriptor Segment, 67-68 
with keyboard, 582 
in SetDateTime structure, 275 
HRDFAIL error class, 289 
Huge memory functions, 182-190 
| 
Idle-time threads, 79-80 
IDs, session, 496 
IGNORE action parameter, 291 
IMPLIB utility, 318-320, 335-336, 339 
Import libraries, 319-320 
command-line parameter for, 357 
IMPLIB for, 339 
linking through, 362-363 
IMPORTS statement 
for linking, 335, 363-364 
in module definition files, 322, 330 
IN instruction, 773, 778 
Independent sessions, 496 
Indirect memory addressing, 3-4 
Infinite retry parallel port parameter, 736-738 
Information message type, 299 
\INFORMATION switch (LINKER), 347, 352 
Inheritance by processes, 27, 33-34 
Initialization option with DosSubSet, 195-196 
Initialization routines for dynamic link libraries, 
337-339 © 
Initialize printer IOCTL function, 740-741 
Input from keyboard, 579-590 
Input Output Privilege Level segments, 6, 325, 
773-775 
and 80386, 778 
functions for, 778-786 
guidelines for developing, 776-778 
setting up of, 775-776 
Ins key, 575, 595 
Instance argument for DATA statement, 326 
Instructions, DOS vs. OS/2, 827 
Integral extendability, 19 
Integrated software, xii-xiii 
Interfaces, 513 
Interim keyboard flags, 591-593 
Internal errors, class for, 289 
Inter-process and inter-thread communication, 
20-22 
and critical sections, 103-110 
for data transfer, 149-164 
flags for, 89-103 
queues for, 88, 232-234 
semaphores for, 110-121 
and mutual exclusion, 122-126 
and signalling, 148 
and synchronization, 126-148 


Index 875 


Interrupts 
with asynchronous drivers, 743 
and BIND utility, 340 
compared to signals, 256 
for devices, 19 
DOS vs. OS/2, 826-827 
and IOPL segments, 774, 776-778 
from keyboard input, 90 
and timer accuracy, 279 
vectors as, 293 
INTREY action parameter, 291 
INTRN error class, 289 
Invalid Opcode vector, 294 
Invalid selector vector, 295 
Invalid Task State Segment vector, 294 
IOCTL functions, 19, 386-387, 419 
asynchronous port. See Asynchronous 
communication port 
disk, 715-735 
keyboard, 709-715 
parallel port, 735-742 
IOPL. SeeInput Output Privilege Level segments 
IPCCALLS.DLL library, 318 
IRET function, 826 


J 


Jittery screen, 661 
JMP instructions, 345 
K 
KBD$ device, 381, 707 
KBD overrun scan code, 800 
KBDCALLS.DLL library, 318, 573 
KbdCharIn function, 579-582, 798 
KbdClose function, 577-578 
KbdDeRegister function, 699 
KbdFlushBuffer function, 579, 589-590 
KbdFreeFocus function, 576-579 
KbdGetFocus function, 576-579 
KbdGetStatus function, 591-598 
KbdOpen function, 576-579 
KbdPeek function, 579-583 
KbdRegister function, 19, 681, 696-699, 702 
KbdSetFGND function, 703 
KbdSetStatus function, 587, 591-598 
KbdShellInit function, 703 
KbdStringIn function, 579, 587-589 
KbdSync function, 702-703 
Keyboard, 573 
access to, 577-579 
and detached processes, 36 
device name for, 381 
focus of, 574-576 
inputs from, 579-590 
IOCTL functions for, 709-715 
libraries for, 318-319 
manipulation functions for, 702-703 
monitors for, 785, 796-801 
and pop-ups, 647 
and Presentation Manager, 495 
scan codes for, 574-575 
serialization of, 682-683 
and sessions, 12-14, 492, 494 
status of, 590-598 
subsystems for, 19, 576-577, 696-699 
type of, 710-711 
Keyboard buffers, 489, 491-492, 495 
clearing of, 579, 589-590 
logical, 574-577 
reading of, 579-583 
L 
LAN environments, 25 
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LAN Manager, xiii 
library for, 318 
Last-in-last-out lists and queues, 225, 227-229, 
234 
Launching of processes, 27 
LDT. See Local Descriptor Table 
LDTR (Local Descriptor Table Register), 4 
Least-recently-used algorithm, 167, 170 
Less than sign (<) with message files, 312 
Level triggered semaphore functions, 114-117 
lib extension and files, 335, 339 
LibFiles parameter for command-line linking, 
357 
Libraries 
and BIND utility, 341 
dynamic link. See Dynamic linking and link 
libraries 
import, 319-320 
and LINKER, 355-356 
run-time. See Run-time dynamic linking 
Libraries parameter for BIND utility, 341 
LIBRARY statement 
for dynamic link libraries, 336 
in module definition files, 321-323 
LIFO lists and queues, 225, 227-229, 234 
Line characteristics for asynchronous commu- 
nications, 743-753 : 
\LINENUMBERS switch (LINKER), 352 
LINK utility and LINKER, 315, 318, 320, 334, 
342-359 
with applications, 334-342 
with Automatic Response File, 358 
from command line, 356-358 
for dynamic link libraries, 336 
and external references, 343-345 
with FAPI applications, 339-341 
limitations of, 354-355 
operation of, 343-344 
with prompts, 355-356 
switches for, 346-354 
See also Dynamic linking and dynamic link 
libraries 
Load argument 
for CODE statement, 323-324 
for DATA statement, 325 
“Load on call” feature, 15 
Load-time dynamic linking, 317-319, 362-364 
Load-time relocations, 354 
Loaded on demand libraries, 321 
Local Descriptor Segment 
and DosGetInfoSeg, 66 
structure for, 68 
Local Descriptor Table, 4-5 
for child processes, 33 
for LRU algorithm, 170 
Local Descriptor Table Register, 4 
Lock drive IOCTL function, 716-718, 731-733 
LOCKED error class, 290 
Locking 
of drives, 716-718, 731-733 
error class for, 290 
of files, 380, 391-392, 411-413 
of screen, 660-664 
of segments, 175, 177-178 
Locus parameters for errors, 291 
Logical buffers, 13, 495 
keyboard, 511, 574-578 
and sessions, 489, 491-492 
video, 510, 644-645, 654-659 
Logical drives, 420, 423-424 


device names for, 381 
IOCTL functions for, 715-735 
maps for, 420 
parameters for, 722-728 
track functions for, 718-722, 728-731 
Logical flow control functions, 756-758 
Long references, LINKER resolution of, 345 
Lowercase letters, LINKER switch for, 353 
LPTx devices, 381, 386, 707 
LRU (least-recently-used algorithm), 167, 170 
M 
/m mapfile parameter for BIND utility, 341-342 
Malloc() function (C), 71, 165 
Map file, 345-346 
\MAP switch (LINKER), 352 
MapFile parameter for command-line linking, 
357 
MAXALLOC field, LINKER switch for, 349 
Maxwait parameter in config.sys, 80 
MDIR command, 440 
MEDIA error class, 290 
MEM error locus parameter, 291 
Memman parameter (CONFIG.SYS), 171 
Memory, 172-173 
allocation of, 27, 165, 234 
CONFIG.SYS file parameters for, 171-172 
expanded, 1 
fragmentation of, 169-170 
indirect addressing of, 3-4 
for IOPL segments and device drivers, 775 
multiple-segment functions for, 182-190 
overcommitment of, 7, 167 
shared functions for, 197-224 
single segment functions for, 174-182 
stack, for threads, 71-72 
suballocation functions for, 190-197 
swapping of, 7-8, 167, 171, 315 
for video adapters, 515, 644 
See also Virtual memory system 
Memory models for C programs, 182 
Menus 
with Presentation Manager, 640 
with Session Manager, 494 
Message retrieval facility, 287-288, 298 
format of, 299-301 
functions for, 301-311 
in RAM, 311-314 
See also Signals and signalling 
MGA. See Monochrome graphics adapters 
Mickeys, 603-604, 625 
Microsoft C Compiler, thread function restric- 
tions on, 71-72 
Milliseconds field of global descriptor, 279 
Minalloc argument for SEGMENTS statement, 
328 
Minutes 
in DateTime structure, 274 
of file creation, 426, 456 
in Global Descriptor Segment, 67-68 
with keyboard, 582 
in SetDateTime structure, 275 
MKDIR command, 440 
MKMSGF utility, 298, 300 
Modem control signals, 743 
Modes, 70 
display, 521-523 
for mouse drivers, 601 
video, 514-515, 520-521 
Module definition files, 318, 320-334 
command-line parameter for, 357-358 


for dynamic link libraries, 337, 361-362, 

364-365 

for IMPLIB utility, 339 

for IOPL segments, 774-775 

with linking, 334-336, 342 

statements for, 321-323 
Modulename argumentfor IMPORTS statement, 

330 
Modules, linking of, 315 
MONCALLS.DLL library, 318 
Monitor chains, 786-789, 791-793, 806 
Monitors 

device. See Character device monitors 

dispatcher for, 788 

display, 514-517 

library for, 318 
Monochrome graphics adapters, 515-516 

attributes with, 540 

modes for, 520 

resolution of, 524 
Monochrome mode, 523 
Monochrome monitors, 515, 517, 529 
Month 

in DateTime structure, 274 

of file creation, 456 

in Global Descriptor Segment, 67-68 

in SetDateTime structure, 275 
Motion 

mouse, 600, 602-604 

segment, 168-170 
MOUCALLS.DLL library, 318 
MouClose function, 605-606, 608-609 
MouDeRegister function, 702 
MouDrawPtr function, 605, 607, 633-635 
MouFlushQue function, 609, 618 
MouGetDevStatus function, 636-637 
MouGetEventMask function, 610, 612-613 
MouGetHotKey function, 638-639 
MouGetNumButtons function, 638 
MouGetNum Mickeys function, 604, 625 
MouGetNumQueE] function, 609, 614-615 
MouGetPtrPos function, 635-636 
MouGetPtrShape function, 605, 625, 628-633 
MouGetScaleFact function, 604, 623-624 
MouOpen function, 605-606, 608-609 
MouReadEventQue function, 608-610, 615-618 
MouRegister function, 19, 681, 699-702 
MouRemovePtr function, 605, 607, 633-634 
Mouse 

buffers for, 489, 491-492 

buttons for, 637-638 

collision areas, 605-606, 633-635 

CONFIG.SYS parameters for, 601-602 

disabled state mode for, 607-608 

events for, 602-603, 606, 609-623 

FAPI support for, 640 

handles for, 605, 608-609 

and hot keys, 638-639 

libraries for, 318-319 

monitors for, 785, 802-803 

pointer for, 599-601, 604-606, 625-633 

and pop-ups, 647 

positioning of, 635-636 

with Presentation Manager, 495, 640 

scale factors for, 603-604, 606, 623-625 

and sessions, 12-14, 492, 494 

status of, 636-637 

subsystem for, 19, 599, 699-702 

supported devices, 640-641 
MOUSE$ device, 381, 707 
MouSetDevStatus function, 600, 607, 636-637 














MouSetEventMask function, 609, 612-613 
MouSetHotKey function, 638-639 
MouSetPtrPos function, 608, 635-636 
MouSetPtrShape function, 604-605, 607, 625, 
628-633 
MouSetScaleFact function, 604, 623-624 
Movement units, mouse, 606-607 
MoveType parameter for DosChgFilePtr, 396- 
397 
.MSG extension, 301 
MSGBIND utility, 299, 311-314 
MSG.DLL library, 319 
Multiple-segment memory functions, 182-190 
Multiple semaphores, 132 
Multiprogramming, 9, 25 
Multitasking, 9-13 
in DOS, xii, 1 
exceptions in, 8 
LDT for, 5 
memory for, 165 
in OS/2, 2 
role of operating system in, 14-22 
Mutual exclusion, 14, 21 
critical sections for, 103-110, 125 
for keyboard and mouse buffers, 492, 494 
for pipes, 152 
semaphores for, 114, 121-126 
for serialization, 682 
with shared memory, 150, 198 
signalling for, 199 
N 
/n name parameter for BIND utility, 342 
NAME statementin module definition files, 321- 
B22 
Names 
for files and devices, 381 
for queues, 230 
resource segment, 372 
for shared memory blocks, 199-201 
National Language Standard keyboard, 799 
National Language Support Status, 581 
Native mode. See Protected mode 
Near references, LINKER resolution of, 345 
NET error locus parameter, 291 
Network, error locus parameter for, 291 
NLS.DLL library, 319 
NMI Interrupt vector, 294 
Nodata argument for EXPORTS statement, 331 
\NODEFAULTLIBRARYSEARCH _- switch 
(LINKER), 352-353 
\NOFARCALL switch (LINKER), 348 
\NOGROUPASSOCIATION switch (LINKER), 
350 
\NOIGNORECASE switch (LINKER), 353 
Nonexclusive semaphores, 117-118 
Non-interruptible devices, 773 
Non-selectable sessions, 496, 501-503 
Non-shared segments, limits on, 173 
Non-transparent pop-ups, 648-649 
\NOPACKCODE switch (LINKER), 348 
NOTFEND error class, 289 
NUL device, 381 
NumLock key, 575, 582, 594 
O 
/o executable_des parameter for BIND utility, 
341 
Object code modules 
import, 319-320 
linking of, 315, 356 
Objectfile parameter for BIND utility, 341 


ObjFiles parameter for command-line linking, 
o57 
Octal numbers in LINKER switches, 346-347 
Offsets in C programs, 172-174 
Opening 
of files, 379, 382-390, 445-446, 449 
of queues, 227, 230-231 
of semaphores, 112-113, 119-120 
OpenMode parameter, 383-384, 389, 394 
Operating mode, function for, 70 
Operating system 
in multitasking environment, 14-22 
protection of, 6-7 
Optimization, LINKER switch for, 349 
Ordering of segments, LINKER switch for, 351 
@ordinal argument for EXPORTS statement, 
331 
OUT instruction, 773, 778 
OUTRES error class, 289 
Overflow Detected vector, 294 
\OVERLAYINTERRUPT switch (LINKER), 350 
Overlays, xiii, 355 
Overscan color, 531 
Owned semaphores, 121 


P 
\PACKCODE switch (LINKER), 348 
Pages, screen, 654 
Palettes, 521, 527-531 
PANIC action parameter, 291 
Parallel ports, 706 
device name for, 381, 386 
IOCTL functions for, 735-742 
monitors for, 785, 802 
Parameters 
for command-line linking, 357-358 
CONFIG.SYS, for memory management, 
171-172 
disk, 423-432 
for messages, 299-300, 302, 305-306 
for mouse driver, 601-602 
passing of, with DosExecPgm, 33-34, 38 
pointer to, 31-32 
pushing of, 16-17, 92 
Parent processes 
termination of child process by, 47 
and video screen, 31 
Parity bit functions, 746-748 
Partial termination of threads, 45 
Partitioning 
of hard drives, 420-421, 423-424, 432-437 
of memory blocks, 190-197 
Pascal convention of parameter pushing, 16-17, 
92 
PATH command, 469 
Path names, 438 
Pause key, 590, 800 
\PAUSE switch (LINKER), 347, 353 
PC-DOS, xi 
Pels. See Pixels 
Percent sign (%) for message parameters, 300 
Periodic timer, 278, 281-282 
Periods (.) with file names, 381 
PhysBufData structure, 661-662 
Physical disk IOCTL functions, 731-735 
Physical memory, 166-168 
Physical video buffers, 644-645, 660-668 
PID. See Process IDs 
Pipes 
for IPC, 88, 150-153 
for redirection, 149 
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STDIN and STDOUT as, 494 
and threads, 28 
Pixels, 644 
in fonts, 677, 679 
for mouse motion, 604 
size of, 521 
Plus sign (+) with linking, 356-357 
POINTER$ device, 381, 707 
Pointer draw mode, 606 
Pointer draw screen driver, 599-601 
Pointers 
file, 379, 395-397 
mouse, 604-606, 625-633 
selectors as, 4 
Pop-up programs, xii, 491-492, 511-512, 646-653 
Portability 
of files, 379-380 
and Presentation Manager, 512 
Ports 
functions to access, 778-780 
hardware I/O, 773 
See alsoAsynchronouscommunication ports; 
Parallel ports 
Positioning of mouse, 635-636 
Preallocation of memory, 165 
Preemptive scheduling system, 12 
Preloaded libraries, 321 
Presentation Manager, xiii, 512-513 
API of, 681-682 
compared to Session Manager, 495 
downloadable fonts in, 678 
for graphics, 643-645 
for mouse, 640 
sessions in, 13 
as standard user interface, 514 
and video manipulation, 509, 655, 660 
Primary threads, 28, 73 
and critical sections, 107 
and signal handling, 256-257 
Print Echo scan code, 801 
Print Flush scan code, 801 
Print-screen operations, 683 
Printers 
device name for, 381 
echo for, 590 
IOCTL functions for, 735-742 
port monitors for, 785 
Priority levels of processes and threads, 
boosting of, 80 
changing of, 78-80 
with device monitors, 789 
functions for, 80-84 
keyboard, 703 
in Local Descriptor Segment, 68 
for threads, 29-30, 279 
Priority ordering of queues, 227-229, 234 
Private address space, 45 
Private combine type, 344 
Privilege argument 
for CODE statement, 325 
for DATA statement, 327 
Privilege levels. See Protection levels 
PRN device, 381, 707 
Process IDs, 30 
for applications, 85 
with DosExecPgm, 39 
function to get, 65-66 
in Local Descriptor Segment, 68 
Processes, +6, 25-28 
background, 31, 256, 492-494 
communication between. See Inter-process 
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and inter-thread communications 
in communications programs, 26 
creation of, 34-43 
data transfer between, 149-164, 197-198 
efficient use of, 85-86 
information functions for, 60-70 
inheritance by, 33-34 
priority of, 78-84 
and queues, 226 
start-up conventions for, 31-33 
synchronization between, 51-60, 87-88, 126- 
148 
termination of, 43-51] 
timer services for, 273 
Processor extension error vector, 295 
Processor Extension Not Available vector, 294 
Processor Extension Segment Overrun vector, 
294 
Program entry point in map file, 346 
Program parameter block, 32 
Program pointer, 32 
Program segment prefixes, 31 
Program selector, 494 
Prompt message type, 299 
Prompts with LINK utility, 355-356 
Protected mode, 1, 3-8 
and assembly language programs, 825 
memory used in, 168 
mouse in, 599, 601 
sessions in, 494, 496 
Protection of files, 5, 380, 391-392, 411-413 
Protection levels, 4, 6-7 
for IOPL segments and device drivers, 775 
of threads, 28 
PROTMODE statement in module definition 
files, 321, 323 
Protocols, communication, 743 
PrtScr key, 683, 801 
Pseudo Print Echo scan code, 801 
PtrLoc structure, 635 
Public address space, 4-5 
Public combine type, 343 
Public symbols, LINKER, 354 
PVB (physical video buffer), 644-645, 660-668 


Qsize for mouse drivers, 601 
QUECALLS.DLL library, 318 
Query functions, 17 
Question marks (?) as wild card characters, 469 
Queue does not exist error, 241 
Queues, 

closing of, 227, 231-232 

creation of, 227-229 

features of, 225-227 

library calls for, 318 

managers for, 233-234 

mouse, 601, 609-623 

opening of, 227, 230-231 

sending and receiving data with, 232-253, 

743, 753-756 

with shared memory, 232-234 

and threads, 28-30 

for transfer of data, 88 

transmit and receive, 743, 753-756 
R 
RAM (random-access memory) 

error locus parameter for, 291 

font tables in, 677-678 

message files in, 311-314 

as system memory, 166 
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TSR requirements for, xii 
RAM semaphores, 111-112 
and DosKillProcess, 48 
example of, 145-148 
handles for, 124 
initialization of, 121 
for inter-process signalling, 148 
variables for, 113 
Range with file locking, 411 
Range exceeded vector, 294 
Raw keyboard mode, 255, 590-592 
Read-only files, 382 
Read track IOCTL function, 718-722, 733-735 
Read/write access mode, 391 
Reading 
with device monitors, 789-790, 794, 796, 
804, 808-810 
of files, 379, 392-393 
Ready threads, 11, 78, 114 
Real mode, 3-4 
and assembly language programs, 825 
memory used in, 168 
mouse in, 599, 601 
rmsize parameter for memory for, 171 
Real mode sessions, 494, 496 
Reboot key and keyboard monitors, 799-800 
Receive queues, 743, 753-756 
Receiver selectors, 208 
Reception of data, IOCTL functions for, 766- 
771 
Recommended BPB, 722-723 
Records 
with device monitors, 794-803 
for pipes, 151-152 
Redirection, 149 
with DosDupHandle, 158-163 
Re-entrancy, 317, 333 
Registering 
of device monitors, 19, 681, 788-794, 803- 
808 
of functions, 686, 697 
Regular threads, 79-80 
Renaming of files, 486 
Repeating key function, 709-710 
Replacement character device modes, 770 
Request to send signal, 743-744, 748-753 
Resend scan code, 800 
Residentname argument for EXPORTS state- 
ment, 331 
Resolution, display, 520, 524, 644 
Resource segments, 372 
Resources, error class for, 289 
Restartable errors. See Exceptions 
RET instruction with threads, 71, 73 
RETRY action parameter, 290 
Return codes with DosExecPgm, 39 
Return key as turn-around character, 591 
Ring 3 DOS library functions, 318 
Ring indicator modem signal, 743 
RM (RMDIR) command, 441 
Rmsize parameter (CONFIG.SYS), 171 
ROM font tables, 677-678 
Root directory, 438 
Router, 682, 702 
Row 
of cursor position, 532-533 
display, 520, 524 
of mouse position, 603 
RS-232 device, communication event status word 
for, 760-762 
RTS (request to send) signal, 743-744, 748-753 


Run-time dynamic linking, 317-318 
example of, 374-377 
functions for, 365-374 
implementation of, 364-365 
module access by, 319 
procedure for, 365-366 
See also Dynamic linking and dynamic link 
libraries 
Running threads, 11, 78 
S 
SAA (System Application Architecture), 512, 
514 
Saving of screen, 668-677 
Scale factors with mouse, 603-604, 606, 623-625 
Scan codes, 574-575, 591 
and keyboard monitors, 798-801 
Scheduler, 11 
parameters for, 67-68 
for threads, 29-30 
Screen 
clearing of, 559 
control functions for, 511-512 
device name for, 381 
images of, 644 
and Presentation Manager, 495 
saving and restoring of, 668-677 
scrolling of, 540, 555-569 
switcher for, 494 
SCREEN$ device, 381, 707 
Screen groups. See Sessions 
Scroll-Lock key, 575, 582, 594 
Scrolling of screen, 540, 555-569 
Searching 
through environment block, 63-65 
for files, 469-486 
Secondary Key Prefix scan code, 800 
Seconds 
in DateTime structure, 274 
of file creation, 426, 456 
in Global Descriptor Segment, 67-68 
with keyboard, 582 
in SetDateTime structure, 275 
Sectors, disk, 393-394, 424-425 
manipulation of, 715 
numbers for, 719, 721 
Segflags argument for SEGMENTS statement, 
328-329 
Segment Not Present exception, 167-168 
Segment Not Present vector, 294 
Segment registers 
and C handling routines, 295 
and disabled interrupts, 778 
Segments 
addressing of, DOS vs. OS/2, 825-826 
descriptor tables for, 3-4 
discardable, 168, 170, 175, 177-178 
IOPL. See Input Output Privilege Level 
segments 
and LINKER, 342-344, 346-355 
map file of, 345-346 
motion of, 168-170 
shared, 88 
specification lines for, 321 
storage of, on hard drives, 167 
swapping of, 170 
See also Memory 
SEGMENTS statement 
for IOPL segments. 776 
in module definition files, 322, 327-330 
\SEGMENTS switch (LINKER), 353-354 




















Segname argument for SEGMENTS statement, 
328 
Selectable sessions, 496, 501-503 
Selector:offset addressing, 3-4, 166 
Selectors, 3-4 
in C programs, 172-174 
of environment block, 60 
for multiple segments, 182-183, 185 
privilege level stored in, 7 
of shared memory blocks, 208-209 
Semaphores 
compared to critical sections, 125-126 
with device monitors, 789 
and DosKillProcess, 48 
handles for, 124 
initialization of, 121 
for IOPL segments, 777 
for IRP, 110-121, 148 
level triggered and edge triggered, 114-117 
for mutual exclusion, 104, 121-126 
and pop-up threads, 680 
for serialization, 682-683 
setting and clearing of, 113, 121, 129-131 
as signals, 87, 148 
for synchronization, 126-148 
and threads, 28 
with timers, 273, 277-278, 280 
variables for, 113 
waiting functions for, 113-117 
Semicolons (;) 
for command-line linking, 358 
in default directory string, 469 
SERDEV error locus parameter, 291 
Serial device, error locus parameter for, 291 
Serial port status functions, 760-766 
Serial Reusable Resources, 87 
and mutual exclusion, 103, 114, 125-126 
protection of, in IOPL segments, 776-777 
Serial= for mouse drivers, 601 
Serialization 
of keyboard, 702 
with subsystems, 682-683 
SESMGR.DLL library, 319 
Session Manager, 13-14, 489 
and compatibility box, 22-23 
components of, 494-495 
library for, 319 
and session creation, 495-496 
Sessions, 12-13, 489-491, 504-508, 510, 645 
and child processes, 30-31 
creation of, 495-499 
selection of, 500-501 
status of, 501-504 
termination of, 499-500 
Set baud rate IOCTL function, 744745 
Set device control block IOCTL function, 767- 
771 
Set frame control IOCTL function, 738-740 
Setinfinite retry status IOCTL function, 736-738 
Set modem control signal IOCTL function, 748- 
750 
Set parity, stop, and data bits IOCTL function, 
746-747 
Set typematic rate and delay IOCTL function, 
709-710 
Set-up of video system, 514-532 
SETCOM40 utility, 829 
SetDateTime structure, 275 
Setting of semaphores, 113, 129-131 
Shape of mouse pointer, 604-605, 625-633 
Shared argument 


for CODE statement, 324 
for DATA statement, 326-327 
Shared files, 384-385, 391 
options for, 176-177, 184-185 
Shared memory segments, 88, 165 
for data transfer, 150, 197-224 
and DosFreeSeg, 179 
huge memory blocks, 183 
limits on, 173 
queues with, 226, 232-234 
and RAM semaphores, 111 
Shift key, 581, 801 
Shift states, 575, 591-592, 594 
Shift Status, 581, 798 
Short references, LINKER resolution of, 345 
Shutdown of mouse, 600-601 
SIGBREAK interrupt, 90, 94, 255-256 
SIGINTR interrupt, 90, 94, 255-256 
Signal Pending error message, 91 
Signals and signalling 
edge triggered semaphores for, 115 
for external events, 255 
flags for, 87, 89-103 
handling of, 73, 256-272 
for mutual exclusion, 199 
semaphores for, 87, 148 
for synchronization, 126-127 
SIGTERM interrupt, 90, 94, 225 
Single segment memory functions, 174-182 
Single Step Interrupt vector, 294 
Size 
of cursor, 532, 534-537 
of files, function for, 444, 467-468 
of memory blocks, 179-180, 186-187, 190- 
197 
of receive queue, 754-756 
Source files for messages, 299-300 
Spaces 
with LINK prompts, 356 
in message headers, 299 
Spawning of processes, 27 
Speaker, IOPL functions for, 773 
SPOOLCP.DLL library, 319 
Spoolers, 319, 785 
SRR. See Serial Reusable Resources 
Stack combine type, 343 
Stack frames, 16 
Stack pointer and API functions, 16 
Stack Segment Overrun or Not Present vector, 
295 
\STACK switch (LINKER), 353 
Stack underflow or overflow vector, 295 
Stacks 
as LIFO lists, 225 
and LINKER, 355 
parameters on, 15-16 
for threads, 71-72 
STACKSIZE statementin module definition files, 
822, 392 
Standard execution environment, 513 
Standard I/O, 414416 
Standard user interface, Sessions manager as, 
489 
Start transmit IOCTL function, 757 
Start-up conventions for processes, 31-33 
StartInfo structure, 497-498 
Static linking, 315-317 
Status 
file, 444-445 
of keyboard, 590-598 
mouse, 636-637 
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of sessions, 501-504 
STDERR device, 386 
I/O with, 414-416 
STDIN device, 386 
I/O with, 414-416 
with KbdStringIn, 587 
with keyboard, 576 
as pipe, 493-494 
STDOUT device, 386 
I/O with, 414416 
as pipe, 493-494 
STI instruction, 777, 780 
Stop bits IOCTL function, 746-748 
Stop transmit IOCTL function, 757 
Storage overcommitment, 7, 167 
Streams, 379 
STUB statementin module definition files, 322, 
332-333 
Suballocation memory functions, 190-197 
Subdirectories, 383n 
creation of, 440-441 
deletion of, 441 
management of, 437-438 
Supplied Buffer Too Small error, 370 
Suspended threads, 76 
Swap-files, 167 
Swappable segments, limits on, 173 
Swappath parameter (CONFIG.SYS), 171-172 
SWAPPER.DAT file, 170-172 
Swapper module, 7-8, 14 
Swapping of memory, 7-8, 14, 167, 171 
Switches, linker, 341-342, 346-354 
Symbol table, LINKER, 354 
Synchronization 
of applications, 682 
by device drivers, 705 
for IOPL segments, 777 
of mouse, 605, 640 
of processes, 21, 51-60, 87-88 
with queues, 233 
semaphores for, 113, 126-148 
of threads, 21, 76-78, 87-88 
Synchronous child processes, 30-31, 37 
SYSFAIL error class, 289 
SysReq keys, 575, 582 
System Application Architecture, 512, 514 
System clock, date and time services for, 273-280 
System environment and child processes, 34 
System failure, class for, 289 
System files, 382, 386 
System memory, management of, 165-166 
System resources 
for child processes, 33-34 
and pop-up threads, 680 
processes and threads as, 30 
System semaphores, 111-112 
creation of, 112-113, 117-119 
example of, 138-144 
timer functions with, 273, 277-278 
System services for IOPL segments device driv- 
ers, 774 
System status information, 67-68 
T 
TAB key, 590 
Task-gates, 6 
Task switching, 9-11 
TEMPSIT error class, 289 
Terminate and stay resident programs, xii, 573- 
574, 646, 821 
Termination 
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action parameter for, 291 
of child sessions, 499-500 
codes for, 39-40, 54 
key for, 590 
of processes, 27, 43-51, 90, 94 
Text-based applications, 514 
Text modes, 521, 523 
display functions for, 538-555 
with EGA, 670 
mouse pointer for, 625 
with Presentation Manager, 640 
Threads, 6, 25-26, 28-29 
communication between. See Inter-process 
and inter-thread communications 
creation of, 71-75 
critical sections in, 105-107 
data sharing between, 21 
dispatching of, 11-12 
and DosCWait, 51 
efficient use of, 85-86 
IDs for, 71-72 
for I/O devices, 26-27 
in Local Descriptor Segment, 68 
priority levels for, 29-30, 78-84 
and semaphores, 117 
synchronization of, 76-78, 87-88, 126-148 
termination of, 43 
and timer functions, 273, 278-280 
Threads parameter in CONFIG.SYS file, 29 
Time 
file creation, 426, 444 
in Global Descriptor Segment, 67-68 
Time critical threads, 79-80 
TIME error class, 290 
Time-outs with ports, 736, 770 
Time slices, 12 
Time stamp 
with keyboard, 579, 582 
in LDT, 170 
for mouse events, 603, 607, 610 
Time windows and device monitors, 791, 803- 
804 
Time zone 
in DateTime structure, 274 
in Global Descriptor Segment, 67-68 
in SetDateTime structure, 275 
Timer functions, 277-280 
Timer_Interval field in global descriptor infor- 
mation, 279 
Timeslice parameter in CONFIG.SYS, 80 
Toggle keys, 575, 594 
Trace mode and DosExecPgm, 38 
Track layout table, 719, 721 
tuples for, 728-729 
Tracks, disk, 394, 715 
formatting and verification of, 728-731 
IOCTL functions for, 718-722, 733-735 
Transfer of data, 88, 149-164, 197-198, 494 
Transmission of data, IOCTL functions for, 766- 
771 
Transmission status IOCTL function, 765-766 
Transmission status word, 761, 765-766 
Transmit immediately IOCTL function, 758 
Transmit queues, 743, 753-756 
Transparent pop-ups, 648-649 
Trap operation code with DosExecPgm, 40 
Tree structures for directory management, 437- 
438 
TSR (Terminate and stay resident) programs, 
xii, 573-574, 646, 821 
Tuples, 728-729 
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Turn-around character, 591-593 

.TXT extension for messages, 299, 301 

Type of device for IOPL segments and device 
drivers, 775 

Typematic rate, function for, 709-710 

U 

Unclassified errors, class for, 290 

UNIX operating system, pipes in, 150 

UNK error class and locus parameter, 290-291 

Unlock drive IOCTL function, 716-718, 731-733 

Unowned semaphores, 121 

Update, file, on directory, 444 

Uppercase letters, LINKER switch for, 353 

USER action parameter, 291 

User interface, Presentation Manager as, 513- 
514 


Vv 
Vectors for exceptions, 293-297 
Verification option, 444-445, 468, 728-731 
Verify track IOCTL function, 718-722, 733-735 
Version, operating system, 67-70 
Vertical resolution, 520, 524 
VGA. See Virtual graphics array adapters 
Video, 509, 643 

ANSI support for, 569-571 

background pop-ups, 646-653 

buffers for, 489, 491-492, 495, 510-511 

configuration for, 511, 514-527 

cursor control, 532-537 

fonts for, 677-680 

libraries for, 318-319 

logical buffers for, 644-645, 654659 

memory for, 494 

palettes for, 527-532 

physical buffers for, 644-645, 660-668 

and Presentation Manager, 512-514 

and processes, 31 

screen groups for, 510 

screen saving, 668-677 

scrolling of, 555-559 

and sessions, 492 

subsystem for, 17, 19, 510-512, 683-695 

text display, 538-555, 559-569 

See also Adapters; Screen 
VIOCALLS.DLL library, 318, 510-511 
Vio_Config structure, 516 
VioDeRegister function, 683, 690 
VioEndPopUp function, 646-653, 669 
VIOFONT structure, 679 
VioGetANSI function, 569-570 
VioGetBuf function, 654656 
VioGetConfig function, 514-519 
VioGetCurPos function, 533 
VioGetCurType function, 534537 
VioGetFont function, 678-680 
VioGetMode function, 515, 520-527 
VioGetPhysBuf function, 660-662 
VioGetState function, 515, 529-532 
VioModeUndo function, 671, 676-677 
VioModeWait function, 670-671, 674-675 
VioPopUp function, 510, 646-653, 669 
VioPrtSc function, 683 
VioPrtScToggle function, 683 
VioReadCellStr function, 542-546 
VioReadCharStr function, 546-548 
VioRegister function, 19, 647, 681, 683-689 
VioSavReDrawUndo function, 670, 673-674 
VioSavReDrawWait function, 670-673 
VioScrLock function, 497, 660-664, 670 
VioScrollDn function, 555-557, 654 


VioScrollLf function, 555, 557-559 
VioScrollRt function, 555, 557-559 
VioScrollUp function, 555-557, 654 
VioScrUnLock function, 497, 660-661, 664, 670 
VioSetANSI function, 569-571 
VioSetCurPos function, 533-534 
VioSetCurType function, 534-537 
VioSetFont function, 678-680 
VioSetMode function, 515, 520-527, 600, 607 
VioSetState function, 515, 528-532 
VioShowBuf function, 655-657 
VioWrtCellStr function, 541-546 
VioWrtCharStr function, 546-547 
VioWrtCharStrAtt function, 548-549 
VioWrtNaAttr function, 551-552 
VioWrtNCell function, 552-553 
VioWrtNChar function, 549-550 
VioWrtStr function, 654 
VioWrtTty function, 414, 540 
Virtual graphics array adapters, 515-517 
direct manipulation of, 645, 660 
font size with, 678 
memory for, 644 
modes for, 520, 522 
pages supported by, 654 
palette for, 529 
resolution of, 524, 644 
Virtual memory system, 2, 7-8, 166-170 
CONFIG.SYS file parameters for, 171-172 
vector for, 293 
Volume labels, 383n, 419, 423-424, 426-427, 715 


WwW 
Wait until Semaphore is clear operation, 122 
Waiting functions for semaphores, 113-117 
Waiting options 

for DosMuxSemWait, 134 

for DosSemSetWait, 130-131 

for DosSemWait, 128-129 
Waiting threads, 11, 78 
“Well-intentioned” applications, 15, 20, 85 
“Well-intentioned” device monitors, 790-791 
Width of cursor, 535 
Wild card characters 

with DosDelete, 487 

with DosMove, 486 

for file searches, 469 
Windows with Presentation Manager, 513 
Write argument for DATA statement, 327 
Write track IOCTL function, 718-722, 733-735 
Writing 

with device monitors, 788-790, 794, 804, 

810-811 

to disk, verification of, 444, 468 

to files, 379, 393-395 
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X for hexadecimal numbers, 347 
XOFF modem signal, 743, 747, 757 
XON modem signal, 743, 757 


Y 
Year 
in DateTime structure, 274 
of file creation, 456 
in Global Descriptor Segment, 67-68 
in SetDateTime structure, 275 
Z 
Zeroes 
division by, exception vector for, 294-295 
for octal numbers, 347 
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